Skip to content

Self-improving AI Employees for everyone

7.3 KB
Raw Blame
/**
 * 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;
}