178 lines
3.5 KiB
Markdown
178 lines
3.5 KiB
Markdown
# @uncaged/json-cas-workflow
|
|
|
|
Workflow integration layer (schemas + types).
|
|
|
|
## Overview
|
|
|
|
`@uncaged/json-cas-workflow` registers eleven JSON Schemas for agent/workflow execution graphs (definitions, thread lifecycle, content, and React-style tool/session nodes) and exports matching TypeScript payload types. Call `registerWorkflowSchemas(store)` once per store to obtain type hashes for each schema.
|
|
|
|
Sits above `@uncaged/json-cas`; typically used with `json-cas-fs` or `createMemoryStore` when building workflow-aware applications.
|
|
|
|
**Dependencies:** `@uncaged/json-cas`
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
bun add @uncaged/json-cas-workflow
|
|
```
|
|
|
|
## API
|
|
|
|
Exported from `src/index.ts`.
|
|
|
|
### Schema registry
|
|
|
|
```typescript
|
|
type WorkflowSchemaHashes = {
|
|
agent: Hash;
|
|
roleSchema: Hash;
|
|
role: Hash;
|
|
workflow: Hash;
|
|
threadStart: Hash;
|
|
threadStep: Hash;
|
|
threadEnd: Hash;
|
|
content: Hash;
|
|
reactSession: Hash;
|
|
reactTurn: Hash;
|
|
reactToolCall: Hash;
|
|
};
|
|
|
|
async function registerWorkflowSchemas(store: Store): Promise<WorkflowSchemaHashes>;
|
|
```
|
|
|
|
Idempotent: safe to call multiple times on the same store (duplicate puts return the same hashes).
|
|
|
|
### Payload types
|
|
|
|
Definition layer:
|
|
|
|
```typescript
|
|
type AgentPayload = {
|
|
package: string;
|
|
version: string;
|
|
config: Record<string, unknown>;
|
|
};
|
|
|
|
type RoleSchemaPayload = Record<string, unknown>;
|
|
|
|
type RolePayload = {
|
|
name: string;
|
|
description: string;
|
|
systemPrompt: string;
|
|
extractPrompt: string;
|
|
schema: Hash; // cas_ref → role-schema
|
|
};
|
|
|
|
type WorkflowTransition = {
|
|
from: string;
|
|
to: string;
|
|
when: string | null;
|
|
};
|
|
|
|
type WorkflowPayload = {
|
|
name: string;
|
|
description: string;
|
|
roles: Record<string, Hash>; // cas_ref → role
|
|
moderator: WorkflowTransition[];
|
|
};
|
|
```
|
|
|
|
Execution layer:
|
|
|
|
```typescript
|
|
type ThreadStartPayload = {
|
|
workflow: Hash;
|
|
input: string;
|
|
depth: number;
|
|
parentThread: Hash | null;
|
|
agents: Record<string, Hash>;
|
|
};
|
|
|
|
type ThreadStepPayload = {
|
|
role: string;
|
|
meta: Record<string, unknown>;
|
|
content: Hash;
|
|
react: Hash;
|
|
start: Hash;
|
|
previous: Hash | null;
|
|
};
|
|
|
|
type ThreadEndPayload = {
|
|
returnCode: number;
|
|
summary: string;
|
|
start: Hash;
|
|
lastStep: Hash;
|
|
};
|
|
|
|
type ContentPayload = {
|
|
text: string;
|
|
};
|
|
```
|
|
|
|
React layer:
|
|
|
|
```typescript
|
|
type ReactTurnTokens = {
|
|
input: number;
|
|
output: number;
|
|
};
|
|
|
|
type ReactSessionPayload = {
|
|
agent: Hash;
|
|
role: string;
|
|
turns: Hash[];
|
|
totalTokens: number;
|
|
durationMs: number;
|
|
};
|
|
|
|
type ReactTurnPayload = {
|
|
input: Hash;
|
|
output: Hash;
|
|
toolCalls: Hash[];
|
|
tokens: ReactTurnTokens;
|
|
latencyMs: number;
|
|
};
|
|
|
|
type ReactToolCallPayload = {
|
|
name: string;
|
|
arguments: Hash;
|
|
result: Hash;
|
|
durationMs: number;
|
|
};
|
|
```
|
|
|
|
(`Hash` is imported from `@uncaged/json-cas` in source; consumers should import `Hash` from `@uncaged/json-cas` when typing their own code.)
|
|
|
|
### Example
|
|
|
|
```typescript
|
|
import { bootstrap, createMemoryStore } from "@uncaged/json-cas";
|
|
import {
|
|
registerWorkflowSchemas,
|
|
type WorkflowPayload,
|
|
} from "@uncaged/json-cas-workflow";
|
|
|
|
const store = createMemoryStore();
|
|
await bootstrap(store);
|
|
|
|
const schemas = await registerWorkflowSchemas(store);
|
|
|
|
const workflowHash = await store.put(schemas.workflow, {
|
|
name: "demo",
|
|
description: "Example workflow",
|
|
roles: {},
|
|
moderator: [],
|
|
} satisfies WorkflowPayload);
|
|
|
|
console.log(workflowHash);
|
|
```
|
|
|
|
## Internal Structure
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `schemas.ts` | JSON Schema definitions and `registerWorkflowSchemas` |
|
|
| `types.ts` | Payload TypeScript types |
|
|
| `index.ts` | Public exports |
|
|
| `index.test.ts` | Registry and schema tests |
|