xingyue
23e2ae9eb4
- ThreadIndexEntry gains status and completedAt fields - createThreadIndexEntry defaults to idle/null - normalizeThreadIndexEntry backward-compat defaults - updateThreadHead resets to idle (衔尾蛇 resume prep) - markThreadSuspended sets status=suspended - New markThreadCompleted(entry, status, now) function - serializeThreadIndexEntry includes new fields Part of #39, closes #40
@united-workforce/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 @ocas/core.
Dependencies: @ocas/core, @ocas/fs
Installation
bun add @united-workforce/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; apiKey: 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 @united-workforce/util-agent (loadWorkflowConfig).