Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
/**
* Wire shapes for Normal mode's employees (server:
* services/employees/summaries.py), parsed with zod.
*
* Parsing is forgiving per field (`.catch`) so one odd value degrades that
* field instead of dropping the whole team list, but an entry without its
* identity (`workflow_id`, `name`) is dropped. `control` goes through the
* same normalizer the editor uses, so both screens read one control shape.
*/
import { z } from 'zod';
import { normalizeWorkflowControlStatus, type WorkflowControlStatus } from '@/contexts/WebSocketContext';
import { COLOR_ROLES } from '@/components/catalog/presentation';
export { COLOR_ROLES, type ColorRole } from '@/components/catalog/presentation';
export const EMPLOYEE_STATUSES = ['working', 'ready', 'paused', 'attention'] as const;
export type EmployeeStatus = (typeof EMPLOYEE_STATUSES)[number];
export const TASK_LABELS = ['Now', 'Next', 'Paused', 'Waiting'] as const;
/** Whether the owner can message the employee on its page: `on` (a talk
* line that replies), `off` (one click adds it) or `unsupported`. */
export const TALK_STATES = ['on', 'off', 'unsupported'] as const;
/** How a hire's own start went: `saved` until it is tried, then `blocked`
* (something to connect first), `running` or `failed`. Only the hire's
* own reply says `starting` (it has just started them). */
export const ACTIVATION_STATES = ['saved', 'blocked', 'starting', 'running', 'failed'] as const;
export const appRefSchema = z.object({
app_id: z.string(),
provider_id: z.string(),
name: z.string(),
icon_ref: z.string().nullable().catch(null).optional(),
connected: z.boolean().catch(false),
supported: z.boolean().catch(true),
});
export type AppRef = z.infer<typeof appRefSchema>;
const appList = z.array(appRefSchema).catch([]);
export const employeeSummarySchema = z.object({
workflow_id: z.string().min(1),
name: z.string(),
/** The photo the owner gave them (the workspace file route); null shows their initial. */
photo_url: z.string().nullable().catch(null),
role: z.string().catch(''),
color_role: z.enum(COLOR_ROLES).catch('agent'),
derived: z.boolean().catch(true),
status: z.enum(EMPLOYEE_STATUSES).catch('ready'),
/** The card's task line; null when the page already says it (waiting for
* the owner's messages, with the message box under the card). */
task: z
.object({ label: z.enum(TASK_LABELS).catch('Now'), text: z.string().catch('') })
.nullable()
.catch(null),
done_today: z.number().int().nonnegative().catch(0),
pending_approvals: z.number().int().nonnegative().catch(0),
apps: appList,
missing_apps: appList,
unsupported_apps: z.array(z.string()).catch([]),
needs_ai: z.boolean().catch(false),
// Optional: zod 4 requires a `z.unknown()` key to be present. A summary
// without one normalizes to "never started".
control: z.unknown().optional(),
watch_node_ids: z.array(z.string()).catch([]),
/** The Canvas board the Workspace shows; null when the graph has none. */
canvas_node_id: z.string().nullable().catch(null),
/** Saved Browser nodes available in this employee's workspace. */
browser_nodes: z.array(z.object({ node_id: z.string().min(1), label: z.string() })).catch([]),
workspace_nodes: z.array(z.object({ kind: z.string().min(1), node_id: z.string().min(1), label: z.string() })).catch([]),
/** A browser waiting for the owner (the agent asked for help). The agent's message is in the live view only. */
browser_request: z
.object({ node_id: z.string().min(1), reason: z.string(), since: z.string().nullable().catch(null) })
.nullable()
.catch(null),
revision: z.number().catch(0),
hired_at: z.string().nullable().catch(null),
/** Null for a workflow built in the editor. */
activation_state: z.enum(ACTIVATION_STATES).nullable().catch(null),
/** The talk line; `agent_node_id` is the agent that answers the owner. */
talk: z
.object({ state: z.enum(TALK_STATES).catch('unsupported'), agent_node_id: z.string().nullable().catch(null) })
.catch({ state: 'unsupported', agent_node_id: null }),
/** Replies wait for the owner's OK, and nothing that sends or spends runs unasked. */
asks_first: z.boolean().catch(false),
/** Saved changes (a tool added in Talk, an edit in Dev mode) wait for a restart. */
pending_changes: z.boolean().catch(false),
has_team: z.boolean().catch(false),
can_give_team: z.boolean().catch(false),
job_progress: z.object({ request_id: z.string(), state: z.string(), message: z.string() }).nullable().catch(null),
});
export type EmployeeSummary = Omit<z.infer<typeof employeeSummarySchema>, 'control'> & {
control: WorkflowControlStatus;
};
const planStepSchema = z.object({
title: z.string(),
detail: z.string().optional().catch(undefined),
role: z.enum(['trigger', 'agent', 'tool', 'workflow']).catch('agent'),
app: z.string().optional().catch(undefined),
});
const ruleItemSchema = z.object({ key: z.string(), label: z.string(), value: z.boolean() });
const workStepSchema = z.object({
id: z.string(),
node_id: z.string().nullable().catch(null),
label: z.string(),
member: z.string().nullable().catch(null),
status: z.enum(['queued', 'waiting', 'running', 'reviewing', 'done', 'failed', 'cancelled', 'stopping']).catch('waiting'),
started_at: z.string().nullable().catch(null),
updated_at: z.string().nullable().catch(null),
});
export const workProgressSchema = z.object({
state: z.string(),
message: z.string(),
started_at: z.string().nullable().catch(null),
updated_at: z.string().nullable().catch(null),
steps: z.array(workStepSchema).catch([]),
truncated: z.boolean().catch(false),
});
export type WorkProgress = z.infer<typeof workProgressSchema>;
export const employeeDetailSchema = employeeSummarySchema.extend({
work_progress: workProgressSchema.nullable().catch(null),
description: z.string().catch(''),
job: z.string().catch(''),
plan: z.array(planStepSchema).catch([]),
rules: z
.object({ ask_first: z.boolean().catch(true), items: z.array(ruleItemSchema).catch([]) })
.partial()
.catch({}),
choices: z.array(z.object({ key: z.string(), label: z.string(), value: z.string() })).catch([]),
trigger_text: z.string().catch(''),
latest_report: z.string().nullable().catch(null),
last_run: z.record(z.string(), z.unknown()).nullable().catch(null),
});
export type EmployeeDetail = Omit<z.infer<typeof employeeDetailSchema>, 'control'> & {
control: WorkflowControlStatus;
};
function withControl<T extends { workflow_id: string; control?: unknown }>(parsed: T): Omit<T, 'control'> & {
control: WorkflowControlStatus;
} {
return { ...parsed, control: normalizeWorkflowControlStatus(parsed.control, parsed.workflow_id) };
}
/** One summary, or null when it lacks its identity. */
export function parseEmployee(raw: unknown): EmployeeSummary | null {
const result = employeeSummarySchema.safeParse(raw);
return result.success ? withControl(result.data) : null;
}
/** A team list, dropping entries that lack their identity. */
export function parseEmployees(raw: unknown): EmployeeSummary[] {
if (!Array.isArray(raw)) return [];
const out: EmployeeSummary[] = [];
for (const item of raw) {
const parsed = parseEmployee(item);
if (parsed) out.push(parsed);
}
return out;
}
export function parseEmployeeDetail(raw: unknown): EmployeeDetail | null {
const result = employeeDetailSchema.safeParse(raw);
return result.success ? withControl(result.data) : null;
}