Files

T

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

Breaking change: Store API keys directly in config.yaml instead of
environment variable names.

## Changes

### @uncaged/workflow-protocol
- Change ProviderConfig.apiKeyEnv: string → apiKey: string
- Update README to reflect new type

### @uncaged/workflow-util-agent
- extract.ts: Remove dotenv loading, use providerEntry.apiKey directly
- storage.ts: Update normalizeProviders to validate apiKey field
- Update error messages to reference apiKey instead of apiKeyEnv

### @uncaged/cli-workflow
- setup.ts: Write actual API key to config.yaml, not .env
- Remove apiKeyEnvName(), loadEnvFile(), saveEnvFile() functions
- Remove getEnvPath() function
- Update cmdSetup to not return envPath in result
- Update README to reflect config.yaml stores API keys
- Fix setup-validate.test.ts to not expect envPath in result

## Verification
- ✅ bun run build passes
- ✅ All tests pass (260/260 in cli-workflow, 55/55 in util-agent)
- ✅ bun run check passes (only pre-existing warnings)

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

2026-05-26 05:23:33 +00:00

src

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

2026-05-26 05:23:33 +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).