Files

T

xiaoju 521d908719 feat(cli): add background thread execution and running threads query

This commit implements issue #456, adding two related capabilities to the uwf CLI:

1. **Background execution mode** for `uwf thread step` (via `--background` flag)
   - Spawns agent execution in a detached background process
   - Returns immediately with thread ID and background status
   - Maintains marker files to track running processes
   - Supports `--count` option to run multiple steps in background
   - Prevents concurrent execution of the same thread

2. **Running threads query** command (`uwf thread running`)
   - Lists all threads currently executing in background
   - Returns thread ID, workflow, current role, PID, and start time
   - Automatically filters out stale markers (dead processes)
   - Empty list when no threads are running

**Key changes:**

- **workflow-protocol**: Added `RunningThreadItem`, `RunningThreadsOutput` types
  Updated `StepOutput` to include `background: boolean | null` field

- **cli-workflow/background**: New module for process management
  - Marker file creation/deletion (atomic operations)
  - PID liveness checking
  - Stale marker cleanup
  - Running threads query

- **cli-workflow/commands/thread**:
  - Updated `cmdThreadStep` to support `--background` and `--_background-worker` flags
  - Added `cmdThreadStepBackground` for spawning detached processes
  - Added `cmdThreadRunning` to list running threads
  - Updated `cmdThreadKill` to terminate background processes

- **cli-workflow/cli**: Added CLI routing for new commands and flags

**Integration:**
- `uwf thread kill` now terminates background processes before archiving
- Foreground execution checks for existing background process and fails if found
- Background worker creates/cleans up marker files automatically
- Marker files stored in `~/.uncaged/workflow/running/*.json`

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

2026-05-24 05:28:29 +00:00

src

feat(cli): add background thread execution and running threads query

2026-05-24 05:28:29 +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: sync all README.md files with current codebase

2026-05-23 15:00:05 +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 Transition = {
  role: string;
  condition: string | null;
  prompt: string;
};

type ConditionDefinition = {
  description: string;
  expression: string;
};

type WorkflowPayload = {
  name: string;
  description: string;
  roles: Record<string, RoleDefinition>;
  conditions: Record<string, ConditionDefinition>;
  graph: Record<string, Transition[]>;
};

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 };

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).