Files

T

xiaoju 45f479e60f feat(protocol): add step-level timing (startedAtMs / completedAtMs) (#489 )

BREAKING CHANGE: StepRecord now requires startedAtMs and completedAtMs fields.
StepEntry now requires durationMs field. Old CAS data without these fields is invalid.

- Add startedAtMs/completedAtMs to StepRecord and StepNodePayload
- Add durationMs to StepEntry (computed: completedAtMs - startedAtMs)
- Update STEP_NODE_SCHEMA to require timing fields as integers
- Record Date.now() before/after agent execution in createAgent
- Show duration in thread read headers (formatStepHeader)
- Update existing test fixtures with timing fields

2026-05-25 08:01:50 +00:00

src

feat(protocol): add step-level timing (startedAtMs / completedAtMs) (#489 )

2026-05-25 08:01:50 +00:00

package.json

feat: add four-phase role description (identity/prepare/execute/report)

2026-05-21 01:41:20 +00:00

README.md

docs: update all documentation for status-based routing (#497 )

2026-05-25 05:52:27 +00:00

tsconfig.json

chore: rename uwf-* → workflow-*, cli-uwf → cli-workflow

2026-05-19 07:52:16 +00:00

README.md

@uncaged/workflow-protocol

Shared TypeScript types and JSON Schema constants for the workflow engine.

Overview

This is the contract layer (Layer 0). It defines WorkflowPayload, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from @uncaged/json-cas.

Dependencies: @uncaged/json-cas, @uncaged/json-cas-fs

Installation

bun add @uncaged/workflow-protocol

API

All exports come from src/index.ts.

JSON Schema constants

START_NODE_SCHEMA: JSONSchema
STEP_NODE_SCHEMA: JSONSchema
WORKFLOW_SCHEMA: JSONSchema

Core identifiers

type CasRef = string      // XXH64 hash, 13-char Crockford Base32
type ThreadId = string    // ULID, 26-char Crockford Base32
type WorkflowName = string
type RoleName = string

Workflow definition

type RoleDefinition = {
  description: string;
  goal: string;
  capabilities: string[];
  procedure: string;
  output: string;
  frontmatter: CasRef;
};

type Target = {
  role: string;
  prompt: string;
};

type WorkflowPayload = {
  name: string;
  description: string;
  roles: Record<string, RoleDefinition>;
  graph: Record<string, Record<string, Target>>;
};

Thread nodes

type StepRecord = {
  role: string;
  output: CasRef;
  detail: CasRef;
  agent: string;
  edgePrompt: string;
};

type StartNodePayload = {
  workflow: CasRef;
  prompt: string;
};

type StepNodePayload = StepRecord & {
  start: CasRef;
  prev: CasRef | null;
};

Moderator context

type StepContext = Omit<StepRecord, "output"> & { output: unknown; content: string | null };

type ModeratorContext = {
  start: StartNodePayload;
  steps: StepContext[];
};

Configuration

type ProviderAlias = string;
type ModelAlias = string;
type AgentAlias = string;

type ProviderConfig = { baseUrl: string; apiKeyEnv: string };
type ModelConfig = {
  provider: ProviderAlias;
  name: string;
};

type AgentConfig = {
  command: string;
  args: string[];
};

type WorkflowConfig = {
  providers: Record<ProviderAlias, ProviderConfig>;
  models: Record<ModelAlias, ModelConfig>;
  agents: Record<AgentAlias, AgentConfig>;
  defaultAgent: AgentAlias;
  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
  defaultModel: ModelAlias;
  modelOverrides: Record<Scenario, ModelAlias> | null;
};

CLI output types

type StartOutput = { workflow: CasRef; thread: ThreadId };

type StepOutput = {
  workflow: CasRef;
  thread: ThreadId;
  head: CasRef;
  done: boolean;
};

type StepEntry = {
  hash: CasRef;
  role: string;
  output: unknown;
  detail: CasRef;
  agent: string;
  timestamp: number;
};

type StartEntry = {
  hash: CasRef;
  workflow: CasRef;
  prompt: string;
  timestamp: number;
};

type ThreadStepsOutput = {
  thread: ThreadId;
  workflow: CasRef;
  steps: [StartEntry, ...StepEntry[]];
};

type ThreadForkOutput = {
  thread: ThreadId;
  forkedFrom: { step: CasRef };
};

type ThreadListItem = {
  thread: ThreadId;
  workflow: CasRef;
  head: CasRef;
};

type ThreadsIndex = Record<ThreadId, CasRef>;

type Scenario = string;

Internal Structure

src/
├── index.ts      Public re-exports
├── types.ts      All type definitions
└── schemas.ts    START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA

Configuration

This package defines WorkflowConfig types only. Runtime config loading lives in @uncaged/workflow-agent-kit (loadWorkflowConfig).