Files

T

xiaoju 984d93a6f5 feat(workflow): add thread/edge location support (#558 )

Implement thread-level and edge-level working directory management:

- Thread-level cwd (required, defaults to process.cwd())
  - Captured at uwf thread start time
  - Stored in StartNodePayload
  - Inherited by all steps unless overridden

- Edge-level location (optional, supports mustache templates)
  - New location: string | null field on Target type
  - Resolved by moderator using previous step's output
  - Example: location: "{{{repoPath}}}"

- Step audit trail
  - Each StepNodePayload records actual cwd where agent executed

Changes:
- workflow-protocol: Add cwd to StartNodePayload & StepRecord, location to Target
- cli-workflow: Thread start captures cwd, moderator resolves location, step execution uses resolved cwd
- workflow-util-agent: Expose cwd in agent context

Tests:
- Protocol type tests (3 scenarios)
- Moderator location resolution tests (5 scenarios)
- Thread-location integration tests (3 scenarios)

All tests pass. Build successful. Backward compatible.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-05-27 15:24:45 +00:00

src

feat(workflow): add thread/edge location support (#558 )

2026-05-27 15:24:45 +00:00

package.json

fix(validate): support enum-based multi-exit and upgrade json-cas to 0.5.3

2026-05-25 13:13:51 +00:00

README.md

refactor(protocol,cli,agent): replace apiKeyEnv with apiKey (#528 )

2026-05-26 05:23:33 +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; 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 @uncaged/workflow-util-agent (loadWorkflowConfig).