Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
/**
* What the employee wants to send and waits for the owner's OK, and the Ask
* first rule (docs-internal/chat_protocol.md, "Approvals"), as TanStack
* queries over `list_approvals` / `decide_approval` / `get_ask_first` /
* `set_ask_first`.
*
* - `useChatApprovals(workflowId)`: the session's recent drafts by id, open
* and settled, and every open one however old (a reply's cards read theirs
* here), and how far the server's clock is from this one, so countdowns
* end when the server's windows do. `turnApprovalIds` says which cards a
* turn shows, and `waitsOnOwner` whether a run waits for the owner's OK.
* - `useDecideApproval(workflowId)`: send, undo, discard, restore, retry,
* dismiss.
* The card moves at once and comes back if the server refuses; every click
* carries a fresh `decision_key`, so a replayed request acts once. Errors
* reach the owner through the hook (`onError`), never the click.
* - `useAskFirst` / `useSetAskFirst`: the workflow's live rule, Ask first
* on or off, or the mode it asks in (RFC-0007 §4.2).
* - `applyApprovalEvent`: an `approval_lifecycle` broadcast (identity only)
* refetches the session's drafts.
*/
import { useEffect } from 'react';
import { useMutation, useQuery, useQueryClient, type QueryClient } from '@tanstack/react-query';
import { z } from 'zod';
import { useWebSocketActions } from '@/contexts/WebSocketContext';
import type { RunSnapshot } from '@/lib/agui/reduceRun';
import { liveApprovalIds, savedApprovalIds } from './parts';
import type { ChatMessage } from './schemas';
export const chatApprovalsKey = (workflowId: string) => ['chatApprovals', workflowId] as const;
export const askFirstKey = (workflowId: string) => ['askFirst', workflowId] as const;
export type ApprovalStatus = 'pending' | 'approved' | 'sending' | 'sent' | 'failed' | 'discarded' | 'expired' | 'cancelled';
const STATUSES: readonly ApprovalStatus[] = ['pending', 'approved', 'sending', 'sent', 'failed', 'discarded', 'expired', 'cancelled'];
const optionalText = z
.string()
.nullable()
.optional()
.catch(undefined)
.transform((value) => (typeof value === 'string' && value ? value : null));
const summarySchema = z
.object({
approval_id: z.string().min(1),
workflow_id: z.string().catch(''),
// gate: an app reply an Approval node holds; tool_call: an employee's
// held call; effect: a call that broke off midway and may have happened.
kind: z.enum(['gate', 'tool_call', 'effect']).catch('gate'),
status: z.enum(STATUSES as [ApprovalStatus, ...ApprovalStatus[]]).catch('pending'),
channel: z.string().catch(''),
action: optionalText,
recipient: z.string().catch(''),
recipient_label: z.string().catch(''),
subject: optionalText,
body: z.string().catch(''),
context_excerpt: optionalText,
details: z.array(z.object({ label: z.string(), value: z.string() })).catch([]),
created_at: optionalText,
expires_at: optionalText,
revision: z.number().catch(0),
max_length: z.number().int().positive().catch(20000),
editable: z.boolean().catch(false),
approved_by: z.enum(['owner', 'auto']).optional().catch(undefined),
edited: z.boolean().optional().catch(undefined),
undo_until: optionalText,
restore_until: optionalText,
consumed_at: optionalText,
outcome: z
.object({
certainty: z.enum(['sent', 'not_sent', 'unknown']).catch('unknown'),
error: z.string().optional().catch(undefined),
at: z.string().optional().catch(undefined),
})
.optional()
.catch(undefined),
outcome_labels: z.object({ sent: z.string(), failed: z.string() }).catch({ sent: 'Message sent', failed: 'Message not sent' }),
run_id: optionalText,
tool_call_id: optionalText,
ui_part_id: optionalText,
deployment_state: optionalText,
// What the held call may do (RFC-0007 §4.1), and whether its tool has no
// spec (the card shows what it runs with, not a message).
approval_class: z.enum(['read', 'write', 'send', 'money']).nullable().optional().catch(null),
generic: z.boolean().optional().catch(undefined),
// Its employee's turn waits on it: no Undo after Allow, no Restore after
// Decline (RFC-0007 §4.6).
waits: z.boolean().optional().catch(undefined),
// The always-allow rule the card offers, or null.
always: z.object({ label: z.string(), scope: z.string() }).nullable().optional().catch(null),
note: optionalText,
})
.transform((raw) => ({
id: raw.approval_id,
workflowId: raw.workflow_id,
kind: raw.kind,
status: raw.status,
channel: raw.channel,
action: raw.action,
recipient: raw.recipient,
recipientLabel: raw.recipient_label || raw.recipient,
subject: raw.subject,
body: raw.body,
contextExcerpt: raw.context_excerpt,
details: raw.details,
createdAt: raw.created_at,
expiresAt: raw.expires_at,
revision: raw.revision,
maxLength: raw.max_length,
editable: raw.editable,
approvedBy: raw.approved_by ?? null,
edited: raw.edited === true,
undoUntil: raw.undo_until,
restoreUntil: raw.restore_until,
consumedAt: raw.consumed_at,
outcome: raw.outcome ? { certainty: raw.outcome.certainty, error: raw.outcome.error ?? null, at: raw.outcome.at ?? null } : null,
/** What the card says once it went, and when it did not (the server's words). */
outcomeLabels: raw.outcome_labels,
runId: raw.run_id,
toolCallId: raw.tool_call_id,
uiPartId: raw.ui_part_id,
deploymentState: raw.deployment_state,
approvalClass: raw.approval_class ?? null,
generic: raw.generic === true,
waits: raw.waits === true,
always: raw.always ?? null,
/** What the owner told the employee on declining. */
note: raw.note,
}));
export type ChatApproval = z.output<typeof summarySchema>;
export function parseApproval(raw: unknown): ChatApproval | null {
const parsed = summarySchema.safeParse(raw);
return parsed.success ? parsed.data : null;
}
export interface ChatApprovals {
byId: ReadonlyMap<string, ChatApproval>;
/** Newest first. */
order: readonly string[];
/** The server's clock minus this one's, in ms. */
offsetMs: number;
/** When this list arrived (this clock). */
receivedAt: number;
}
export const NO_APPROVALS: ChatApprovals = { byId: new Map(), order: [], offsetMs: 0, receivedAt: 0 };
/** Still the owner's to act on, or on its way. */
export function isOpenApproval(approval: ChatApproval, nowMs: number): boolean {
switch (approval.status) {
case 'pending':
case 'sending':
case 'failed':
return true;
case 'approved':
return approval.consumedAt === null;
case 'discarded':
return approval.restoreUntil !== null && Date.parse(approval.restoreUntil) > nowMs;
default:
return false;
}
}
/** The cards a turn shows: those its saved reply names and its run
* announced, then, while the turn holds its run, any other the run made,
* oldest first. A call can wait for days, longer than the server keeps a
* run's activities, so the run keeps its cards (RFC-0007 §4.7). */
export function turnApprovalIds(message: ChatMessage | null, run: RunSnapshot | null, approvals: ChatApprovals): string[] {
const ids = new Set([...savedApprovalIds(message?.parts), ...liveApprovalIds(run?.activities)]);
if (run) for (const id of [...approvals.order].reverse()) if (approvals.byId.get(id)?.runId === run.runId) ids.add(id);
return [...ids];
}
/** Whether a run waits for the owner's OK on one of its calls (RFC-0007
* §4.6). */
export function waitsOnOwner(approvals: ChatApprovals, runId: string | null | undefined): boolean {
if (!runId) return false;
for (const approval of approvals.byId.values()) if (approval.runId === runId && approval.waits && approval.status === 'pending') return true;
return false;
}
/** Seconds left until `until` on the server's clock, never below 0. */
export function secondsLeft(until: string | null, offsetMs: number, nowMs = Date.now()): number {
if (!until) return 0;
const end = Date.parse(until);
if (Number.isNaN(end)) return 0;
return Math.max(0, Math.ceil((end - (nowMs + offsetMs)) / 1000));
}
type ListReply = { success?: boolean; approvals?: unknown; server_time?: string; error?: string };
export function readApprovals(reply: ListReply | undefined, receivedAt: number): ChatApprovals {
const list = Array.isArray(reply?.approvals) ? reply.approvals : [];
const byId = new Map<string, ChatApproval>();
const order: string[] = [];
for (const raw of list) {
const approval = parseApproval(raw);
if (!approval || byId.has(approval.id)) continue;
byId.set(approval.id, approval);
order.push(approval.id);
}
const serverMs = reply?.server_time ? Date.parse(reply.server_time) : Number.NaN;
return { byId, order, offsetMs: Number.isNaN(serverMs) ? 0 : serverMs - receivedAt, receivedAt };
}
export function useChatApprovals(workflowId: string | null) {
const { sendRequest, isReady } = useWebSocketActions();
return useQuery<ChatApprovals, Error>({
queryKey: chatApprovalsKey(workflowId ?? ''),
queryFn: async () => {
// The newest 100, and every one still open: a call can wait for days
// behind newer ones (RFC-0007 §4.7). An open one not among the newest
// is older than all of them, so it goes last.
const [recent, open] = await Promise.all(
(['recent', 'open'] as const).map((status) => sendRequest<ListReply>('list_approvals', { workflow_id: workflowId, status, limit: 100 })),
);
const failed = [recent, open].find((reply) => reply?.success === false);
if (failed) throw new Error(failed.error || 'Could not load the drafts');
const rows = (reply: ListReply | undefined) => (Array.isArray(reply?.approvals) ? reply.approvals : []);
return readApprovals({ ...recent, approvals: [...rows(recent), ...rows(open)] }, Date.now());
},
enabled: isReady && Boolean(workflowId),
// Runs make drafts while no chat is open: always look again on open.
refetchOnMount: 'always',
staleTime: 0,
});
}
export type Decision = 'send' | 'undo' | 'discard' | 'restore' | 'retry' | 'dismiss';
export interface DecideInput {
approval: ChatApproval;
decision: Decision;
text?: string;
subject?: string;
confirm?: boolean;
/** With send: also save the always-allow rule the card offers. */
always?: boolean;
/** With discard: what the employee should do instead. */
note?: string;
}
export class DecideError extends Error {
constructor(
readonly code: string,
message: string,
) {
super(message);
}
}
const DECIDE_ERRORS: Record<string, string> = {
already_decided: 'That draft was already handled.',
expired: 'That draft expired before it was sent.',
cancelled: 'That draft was cancelled.',
too_late: 'Too late: it has already gone.',
approval_conflict: 'That draft changed meanwhile. Look again.',
send_unavailable: 'Nothing can send it right now. Try again in a moment.',
not_found: 'That draft is gone.',
invalid_request: 'That can’t be sent as it is.',
};
export function decisionKey(): string {
try {
if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
} catch {
// Not a secure context.
}
return `k-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
}
/** What the card shows while the server answers. */
export function optimistic(approval: ChatApproval, decision: Decision, nowMs: number, offsetMs: number): ChatApproval {
const serverNow = nowMs + offsetMs;
const soon = (seconds: number) => new Date(serverNow + seconds * 1000).toISOString();
switch (decision) {
case 'send':
// A call its turn waits on runs at once: no Undo.
return { ...approval, status: 'approved', undoUntil: approval.waits ? null : soon(5), outcome: null };
case 'retry':
// A retried call is a draft again, whoever made it.
return { ...approval, status: 'approved', undoUntil: soon(5), outcome: null, waits: false };
case 'undo':
case 'restore':
return { ...approval, status: 'pending', undoUntil: null, restoreUntil: null };
case 'discard':
return { ...approval, status: 'discarded', restoreUntil: approval.waits ? null : approval.kind === 'gate' ? soon(5) : approval.expiresAt };
case 'dismiss':
return { ...approval, status: 'cancelled' };
}
}
type DecideReply = { success?: boolean; error?: string; detail?: string; approval?: unknown };
function replace(data: ChatApprovals | undefined, approval: ChatApproval): ChatApprovals | undefined {
if (!data) return data;
const byId = new Map(data.byId);
byId.set(approval.id, approval);
const order = data.order.includes(approval.id) ? data.order : [approval.id, ...data.order];
return { ...data, byId, order };
}
export function useDecideApproval(workflowId: string, onError?: (error: DecideError, input: DecideInput) => void) {
const { sendRequest } = useWebSocketActions();
const queryClient = useQueryClient();
const key = chatApprovalsKey(workflowId);
return useMutation<ChatApproval | null, DecideError, DecideInput, { previous: ChatApprovals | undefined }>({
mutationFn: async ({ approval, decision, text, subject, confirm, always, note }) => {
let reply: DecideReply | undefined;
try {
reply = await sendRequest<DecideReply>('decide_approval', {
approval_id: approval.id,
decision,
decision_key: decisionKey(),
...(text !== undefined ? { text } : {}),
...(subject !== undefined ? { subject } : {}),
...(confirm ? { confirm: true } : {}),
...(always ? { always: true } : {}),
...(note ? { note } : {}),
});
} catch {
throw new DecideError('transport', 'That didn’t reach the server. Try again.');
}
const current = parseApproval(reply?.approval);
if (reply?.success === false) {
if (current) queryClient.setQueryData<ChatApprovals>(key, (data) => replace(data, current));
const code = reply.error || 'failed';
throw new DecideError(code, reply.detail || DECIDE_ERRORS[code] || 'That didn’t work. Try again.');
}
return current;
},
onMutate: async ({ approval, decision }) => {
await queryClient.cancelQueries({ queryKey: key });
const previous = queryClient.getQueryData<ChatApprovals>(key);
const offsetMs = previous?.offsetMs ?? 0;
queryClient.setQueryData<ChatApprovals>(key, (data) => replace(data, optimistic(approval, decision, Date.now(), offsetMs)));
return { previous };
},
onSuccess: (approval) => {
if (approval) queryClient.setQueryData<ChatApprovals>(key, (data) => replace(data, approval));
},
onError: (error, input, context) => {
// The refusal carried the draft as it is: keep that. Otherwise put
// the card back.
if (context && error.code === 'transport') queryClient.setQueryData(key, context.previous);
onError?.(error, input);
},
onSettled: () => {
void queryClient.invalidateQueries({ queryKey: key });
},
});
}
/** What the employee asks first about (RFC-0007 §4.2): anything outside
* (sends and money), everything (its own changes too), or only money and
* deletes. */
export type AskMode = 'outside' | 'everything' | 'money_only';
const ASK_MODES: readonly AskMode[] = ['outside', 'everything', 'money_only'];
const askModeOf = (value: unknown): AskMode | null => ((ASK_MODES as readonly unknown[]).includes(value) ? (value as AskMode) : null);
export interface AskFirst {
/** null: the workflow has no rule (its tool calls are never held). */
askFirst: boolean | null;
/** The mode, or Ask first's meaning while the owner has chosen none;
* null with no rule. */
mode: AskMode | null;
revision: number;
}
export function useAskFirst(workflowId: string | null) {
const { sendRequest, isReady } = useWebSocketActions();
return useQuery<AskFirst, Error>({
queryKey: askFirstKey(workflowId ?? ''),
queryFn: async () => {
const reply = await sendRequest<{ success?: boolean; ask_first?: unknown; mode?: unknown; revision?: unknown; error?: string }>(
'get_ask_first',
{ workflow_id: workflowId },
);
if (reply?.success === false) throw new Error(reply.error || 'Could not read Ask first');
return {
askFirst: typeof reply?.ask_first === 'boolean' ? reply.ask_first : null,
mode: askModeOf(reply?.mode),
revision: typeof reply?.revision === 'number' ? reply.revision : 0,
};
},
enabled: isReady && Boolean(workflowId),
refetchOnMount: 'always',
staleTime: 0,
});
}
export interface SetAskFirstResult extends AskFirst {
repliesGated: boolean;
needsApply: boolean;
}
/** Ask first on or off (the chip), or a mode (the mode menu). */
export type AskFirstChange = boolean | AskMode;
/** The rule a change makes: a mode also writes the Ask first it means, so a
* generation that reads only Ask first keeps reading it. */
function changed(change: AskFirstChange): Pick<AskFirst, 'askFirst' | 'mode'> {
if (typeof change === 'boolean') return { askFirst: change, mode: change ? 'outside' : 'money_only' };
return { askFirst: change !== 'money_only', mode: change };
}
export function useSetAskFirst(workflowId: string, onError?: (message: string) => void) {
const { sendRequest } = useWebSocketActions();
const queryClient = useQueryClient();
const key = askFirstKey(workflowId);
return useMutation<SetAskFirstResult, Error, AskFirstChange, { previous: AskFirst | undefined }>({
mutationFn: async (change) => {
const current = queryClient.getQueryData<AskFirst>(key);
const reply = await sendRequest<{
success?: boolean;
error?: string;
ask_first?: unknown;
mode?: unknown;
revision?: unknown;
replies_gated?: unknown;
needs_apply?: unknown;
}>('set_ask_first', {
workflow_id: workflowId,
...(typeof change === 'boolean' ? { ask_first: change } : { mode: change }),
...(current ? { expected_revision: current.revision } : {}),
});
if (reply?.success === false) {
throw new Error(reply.error === 'rule_conflict' ? 'Ask first changed meanwhile. Look again.' : 'Couldn’t change Ask first. Try again.');
}
const expected = changed(change);
return {
askFirst: typeof reply?.ask_first === 'boolean' ? reply.ask_first : expected.askFirst,
mode: askModeOf(reply?.mode) ?? expected.mode,
revision: typeof reply?.revision === 'number' ? reply.revision : 0,
repliesGated: reply?.replies_gated === true,
needsApply: reply?.needs_apply === true,
};
},
onMutate: async (change) => {
await queryClient.cancelQueries({ queryKey: key });
const previous = queryClient.getQueryData<AskFirst>(key);
queryClient.setQueryData<AskFirst>(key, { ...changed(change), revision: previous?.revision ?? 0 });
return { previous };
},
onSuccess: (result) => {
queryClient.setQueryData<AskFirst>(key, { askFirst: result.askFirst, mode: result.mode, revision: result.revision });
},
onError: (error, _value, context) => {
if (context) queryClient.setQueryData(key, context.previous);
onError?.(error.message);
},
onSettled: () => {
void queryClient.invalidateQueries({ queryKey: key });
},
});
}
interface ApprovalEnvelope {
specversion?: string;
type?: string;
data?: { workflow_id?: string; approval_id?: string } | null;
}
/** Apply one `approval_lifecycle` envelope. Exported for tests. */
export function applyApprovalEvent(queryClient: QueryClient, event: ApprovalEnvelope): void {
if (!event || event.specversion !== '1.0') return;
const workflowId = event.data?.workflow_id;
if (!workflowId) return;
void queryClient.invalidateQueries({ queryKey: chatApprovalsKey(workflowId) });
}
/** Keep a chat's drafts current while it is mounted. */
export function useApprovalEvents(): void {
const queryClient = useQueryClient();
const { addEventListener } = useWebSocketActions();
useEffect(() => addEventListener('approval_lifecycle', (data) => applyApprovalEvent(queryClient, data)), [addEventListener, queryClient]);
}