Approval

/**
 * ApprovalGate — headless core.
 * Pattern: letting a human authorize an agent action before it executes.
 * Anatomy: Preview · Details · Scope · Approve · Reject · Edit · Editor · Expiry · Receipt · Revoke · Changed
 *
 * The state machine IS the pattern definition. Anatomy parts that a vendor
 * does not implement are switched off via ApprovalGateConfig (see presets in
 * @agentsandhumans/patterns-ui) — which is how the playground can render
 * "ApprovalGate as Claude Code does it" against "as Codex does it".
 *
 * Lifecycle (spec 2026-10-04 §2):
 *   pending → editing → pending   (saving an edit makes a new request version)
 *   pending → granted | denied | expired
 *   granted → revoked
 * APPROVE, REJECT, EDIT and EXPIRE act only while pending. A decision is for one
 * request version, never "the latest": when the host sends a new version after a
 * decision, that decision no longer applies and the gate asks again.
 */
import * as React from 'react';
import {
  createEvent,
  type ActionRequest,
  type ApprovalDecision,
  type ApprovalOutcome,
  type ApprovalRequestedPayload,
  type ApprovalRevocation,
  type ApprovalScope,
  type EventDraft,
  type InteractionEventHandler,
} from '@/lib/interaction-contract';

// The shared records live in the contract; re-exported so existing imports keep working.
export type { ActionRequest, ApprovalDecision, ApprovalOutcome, ApprovalRevocation, ApprovalScope } from '@/lib/interaction-contract';

export type ApprovalState = 'pending' | 'editing' | 'granted' | 'denied' | 'expired' | 'revoked';

export interface ApprovalGateConfig {
  /** Which scope options this implementation offers. Empty = no Scope part. */
  scopes: ApprovalScope[];
  defaultScope: ApprovalScope;
  /** Auto-timeout in ms per request version; null = the Expiry part is absent. */
  expiresInMs: number | null;
  /** Whether the human can edit the proposal instead of accept/reject. */
  allowEdit: boolean;
}

export const defaultConfig: ApprovalGateConfig = {
  scopes: ['once', 'session', 'standing'],
  defaultScope: 'once',
  expiresInMs: null,
  allowEdit: true,
};

/** Words a person reads for each scope. */
export const scopeLabel: Record<ApprovalScope, string> = {
  once: 'once',
  session: 'this session',
  standing: 'always',
};

export type Event =
  | { type: 'APPROVE'; at?: string }
  | { type: 'REJECT'; at?: string }
  | { type: 'EXPIRE'; at?: string }
  | { type: 'EDIT' }
  | { type: 'SET_DRAFT'; args: unknown; valid?: boolean }
  | { type: 'SAVE_EDIT' }
  | { type: 'CANCEL_EDIT' }
  | { type: 'SET_SCOPE'; scope: ApprovalScope }
  | { type: 'REVOKE'; at?: string }
  /** The host sent a request: a new id, or a version above the last one it sent. */
  | { type: 'REQUEST_CHANGED'; request: ActionRequest }
  /** The host verified and stored the current decision. */
  | { type: 'RECEIPT'; serverReceiptId: string };

export interface MachineState {
  state: ApprovalState;
  scope: ApprovalScope;
  /** The version on screen: the host's, or the one an edit made. */
  request: ActionRequest;
  /** The last version the host sent; host updates are compared with this. */
  hostVersion: number;
  /** Set when the version on screen came from the person's edit. */
  editedArgs?: unknown;
  /** The args being edited, while editing. */
  draft: unknown;
  draftValid: boolean;
  decision: ApprovalDecision | null;
  revocation: ApprovalRevocation | null;
  /** The decision a later request version replaced. It no longer applies. */
  superseded: ApprovalDecision | null;
}

export function initialState(request: ActionRequest, scope: ApprovalScope = defaultConfig.defaultScope): MachineState {
  return {
    state: 'pending',
    scope,
    request,
    hostVersion: request.version,
    draft: request.args,
    draftValid: true,
    decision: null,
    revocation: null,
    superseded: null,
  };
}

function decide(s: MachineState, outcome: ApprovalOutcome, at?: string): MachineState {
  const decision: ApprovalDecision = {
    requestId: s.request.id,
    requestVersion: s.request.version,
    outcome,
    scope: s.scope,
    decidedAt: at ?? new Date().toISOString(),
  };
  if (s.editedArgs !== undefined) decision.editedArgs = s.editedArgs;
  return { ...s, state: outcome, decision };
}

export function reducer(s: MachineState, e: Event): MachineState {
  switch (e.type) {
    case 'APPROVE':
      return s.state === 'pending' ? decide(s, 'granted', e.at) : s;
    case 'REJECT':
      return s.state === 'pending' ? decide(s, 'denied', e.at) : s;
    case 'EXPIRE':
      return s.state === 'pending' ? decide(s, 'expired', e.at) : s;
    case 'EDIT':
      return s.state === 'pending' ? { ...s, state: 'editing', draft: s.request.args, draftValid: true } : s;
    case 'SET_DRAFT':
      return s.state === 'editing' ? { ...s, draft: e.args, draftValid: e.valid ?? true } : s;
    case 'SAVE_EDIT':
      if (s.state !== 'editing' || !s.draftValid) return s;
      return {
        ...s,
        state: 'pending',
        request: { ...s.request, version: s.request.version + 1, args: s.draft },
        editedArgs: s.draft,
      };
    case 'CANCEL_EDIT':
      return s.state === 'editing' ? { ...s, state: 'pending', draft: s.request.args, draftValid: true } : s;
    case 'SET_SCOPE':
      return s.state === 'pending' || s.state === 'editing' ? { ...s, scope: e.scope } : s;
    case 'REVOKE':
      if (s.state !== 'granted' || !s.decision) return s;
      return {
        ...s,
        state: 'revoked',
        revocation: {
          requestId: s.decision.requestId,
          requestVersion: s.decision.requestVersion,
          revokedAt: e.at ?? new Date().toISOString(),
        },
      };
    case 'REQUEST_CHANGED': {
      const r = e.request;
      const sameRequest = r.id === s.request.id;
      // A duplicate or an older version changes nothing.
      if (sameRequest && r.version <= s.hostVersion) return s;
      return {
        ...initialState(r, s.scope),
        // A new version of the same request carries the earlier decision as a record only.
        superseded: sameRequest ? s.decision ?? s.superseded : null,
      };
    }
    case 'RECEIPT':
      if (!s.decision || s.decision.serverReceiptId === e.serverReceiptId) return s;
      return { ...s, decision: { ...s.decision, serverReceiptId: e.serverReceiptId } };
  }
}

const decisionKey = (d: ApprovalDecision) => `${d.requestId}@${d.requestVersion}:${d.outcome}:${d.decidedAt}`;

/**
 * The contract events one transition produces (spec 2026-10-04 §1). `prev` is
 * null on mount. `correlationId` defaults to the request id; pass the plan id
 * to tie the approval to the plan it runs.
 */
export function approvalEvents(prev: MachineState | null, next: MachineState, correlationId?: string): EventDraft[] {
  const corr = correlationId ?? next.request.id;
  const out: EventDraft[] = [];
  const newVersion =
    prev === null || prev.request.id !== next.request.id || prev.request.version !== next.request.version;
  if (newVersion && !isSettled(next.state)) {
    const edited = prev !== null && prev.request.id === next.request.id && next.editedArgs !== undefined;
    const payload: ApprovalRequestedPayload = { request: next.request, edited };
    out.push({ type: 'approval.requested', actor: edited ? 'human' : 'agent', correlationId: corr, payload });
  }
  const d = next.decision;
  if (d && (!prev?.decision || decisionKey(prev.decision) !== decisionKey(d))) {
    out.push({ type: `approval.${d.outcome}`, actor: d.outcome === 'expired' ? 'system' : 'human', correlationId: corr, payload: d });
  }
  if (next.revocation && next.revocation !== prev?.revocation) {
    out.push({ type: 'approval.revoked', actor: 'human', correlationId: corr, payload: next.revocation });
  }
  return out;
}

export const isSettled = (state: ApprovalState) => state !== 'pending' && state !== 'editing';

interface ApprovalGateContext extends MachineState {
  config: ApprovalGateConfig;
  /** When the current version expires (epoch ms); null when expiry is off. */
  deadline: number | null;
  send: (e: Event) => void;
}

const Ctx = React.createContext<ApprovalGateContext | null>(null);

export function useApprovalGate(): ApprovalGateContext {
  const ctx = React.useContext(Ctx);
  if (!ctx) throw new Error('ApprovalGate parts must be used inside <ApprovalGate.Root>');
  return ctx;
}

export interface RootProps {
  /** The action the agent asks to take. Send a new version whenever it changes. */
  request: ActionRequest;
  config?: Partial<ApprovalGateConfig>;
  /** Called once per decision. Verify it server-side, then pass back serverReceiptId. */
  onDecision?: (d: ApprovalDecision) => void;
  onRevoke?: (r: ApprovalRevocation) => void;
  /** The id your server returned after storing the current decision. Until then the receipt is local. */
  serverReceiptId?: string;
  /** One agent run; stamped on every contract event. Defaults to a generated id. */
  runId?: string;
  /** Carried on every approval.* event. Pass the plan id so the approval points at the plan; defaults to the request id. */
  correlationId?: string;
  /** Contract events: approval.requested, approval.granted | denied | expired, approval.revoked. */
  onEvent?: InteractionEventHandler;
  children: React.ReactNode;
}

function Root({
  request,
  config: partial,
  onDecision,
  onRevoke,
  serverReceiptId,
  runId,
  correlationId,
  onEvent,
  children,
}: RootProps) {
  const config = React.useMemo(() => ({ ...defaultConfig, ...partial }), [partial]);
  const [machine, send] = React.useReducer(reducer, request, (r) => initialState(r, config.defaultScope));

  // Host updates: a new id, or a higher version, replaces what is on screen.
  React.useEffect(() => {
    send({ type: 'REQUEST_CHANGED', request });
    // The id and version identify a request; other fields change only with the version.
  }, [request.id, request.version]);

  // The receipt id applies to the decision on screen when the host sends it.
  React.useEffect(() => {
    if (serverReceiptId) send({ type: 'RECEIPT', serverReceiptId });
  }, [serverReceiptId]);

  // One expiry window per request version. Editing pauses the gate but not the clock.
  const versionKey = `${machine.request.id}@${machine.request.version}`;
  const [opened, setOpened] = React.useState({ key: versionKey, at: Date.now() });
  if (opened.key !== versionKey) setOpened({ key: versionKey, at: Date.now() });
  const deadline = config.expiresInMs == null ? null : opened.at + config.expiresInMs;

  React.useEffect(() => {
    if (deadline == null || machine.state !== 'pending') return;
    const t = setTimeout(() => send({ type: 'EXPIRE' }), Math.max(0, deadline - Date.now()));
    return () => clearTimeout(t);
  }, [deadline, machine.state]);

  const emitted = React.useRef<string | null>(null);
  React.useEffect(() => {
    if (!machine.decision) return;
    const key = decisionKey(machine.decision);
    if (key === emitted.current) return;
    emitted.current = key;
    onDecision?.(machine.decision);
  }, [machine.decision, onDecision]);

  const revoked = React.useRef<ApprovalRevocation | null>(null);
  React.useEffect(() => {
    if (machine.revocation && machine.revocation !== revoked.current) {
      revoked.current = machine.revocation;
      onRevoke?.(machine.revocation);
    }
  }, [machine.revocation, onRevoke]);

  const fallbackRun = React.useId();
  const run = runId ?? fallbackRun;
  const emit = React.useRef(onEvent);
  emit.current = onEvent;
  const prevMachine = React.useRef<MachineState | null>(null);
  React.useEffect(() => {
    const drafts = approvalEvents(prevMachine.current, machine, correlationId);
    prevMachine.current = machine;
    for (const d of drafts) emit.current?.(createEvent(run, d));
  }, [machine, correlationId, run]);

  const value = React.useMemo(() => ({ ...machine, config, deadline, send }), [machine, config, deadline]);

  return (
    <Ctx.Provider value={value}>
      <div
        role="group"
        aria-label="Approval required"
        data-pattern="approval-gate"
        data-part="root"
        data-state={machine.state}
        data-request-id={machine.request.id}
        data-request-version={machine.request.version}
      >
        {children}
      </div>
    </Ctx.Provider>
  );
}

export function formatArgs(args: unknown): string {
  if (typeof args === 'string') return args;
  if (args === undefined) return '';
  return JSON.stringify(args, null, 2);
}

/** The proposed action. Renders the action and its args unless children replace them. */
function Preview({ children }: { children?: React.ReactNode | ((r: ActionRequest) => React.ReactNode) }) {
  const { state, request } = useApprovalGate();
  const body =
    typeof children === 'function' ? (
      children(request)
    ) : children !== undefined ? (
      children
    ) : (
      <>
        <strong data-part="action">{request.action}</strong>
        {request.args !== undefined && <div data-part="args">{formatArgs(request.args)}</div>}
      </>
    );
  return (
    <div data-part="preview" data-state={state}>
      {body}
    </div>
  );
}

/** Version, what it touches, what follows, whether it can be undone. */
function Details() {
  const { request, editedArgs } = useApprovalGate();
  return (
    <dl data-part="details">
      <dt>Version</dt>
      <dd>
        {request.version}
        {editedArgs !== undefined ? ' (your edit)' : ''}
      </dd>
      {request.resources.length > 0 && (
        <>
          <dt>Touches</dt>
          <dd>{request.resources.join(', ')}</dd>
        </>
      )}
      {request.consequences && (
        <>
          <dt>What happens</dt>
          <dd>{request.consequences}</dd>
        </>
      )}
      <dt>Undo</dt>
      <dd data-reversible={request.reversible}>{request.reversible ? 'Can be undone' : 'Cannot be undone'}</dd>
    </dl>
  );
}

/** What is authorized: once | session | standing. Renders nothing when the implementation has no scopes. */
function Scope() {
  const { config, scope, state, send } = useApprovalGate();
  const name = React.useId();
  if (config.scopes.length === 0) return null;
  return (
    <fieldset data-part="scope" data-state={state} disabled={isSettled(state)}>
      <legend>Allow</legend>
      {config.scopes.map((s) => (
        <label key={s}>
          <input
            type="radio"
            name={name}
            value={s}
            checked={scope === s}
            onChange={() => send({ type: 'SET_SCOPE', scope: s })}
          />
          {scopeLabel[s]}
        </label>
      ))}
    </fieldset>
  );
}

type TriggerProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'>;

function Approve(props: TriggerProps) {
  const { state, send } = useApprovalGate();
  return (
    <button type="button" data-part="approve" disabled={state !== 'pending'} onClick={() => send({ type: 'APPROVE' })} {...props} />
  );
}

function Reject(props: TriggerProps) {
  const { state, send } = useApprovalGate();
  return (
    <button type="button" data-part="reject" disabled={state !== 'pending'} onClick={() => send({ type: 'REJECT' })} {...props} />
  );
}

/** Opens the Editor. Only from pending; renders nothing when the implementation has no edit. */
function Edit(props: TriggerProps) {
  const { state, config, send } = useApprovalGate();
  if (!config.allowEdit) return null;
  return (
    <button
      type="button"
      data-part="edit"
      aria-expanded={state === 'editing'}
      disabled={state !== 'pending'}
      onClick={() => send({ type: 'EDIT' })}
      {...props}
    />
  );
}

/**
 * The args as text while editing. String args edit as they are; anything else edits as JSON,
 * and Save stays off until the JSON parses. Saving makes the next request version.
 */
function Editor({ label = 'Edit the request', save = 'Save edit', cancel = 'Cancel' }: { label?: string; save?: string; cancel?: string }) {
  const { state, request, draft, draftValid, send } = useApprovalGate();
  const [text, setText] = React.useState(() => formatArgs(draft));
  const id = React.useId();
  React.useEffect(() => {
    if (state === 'editing') setText(formatArgs(request.args));
  }, [state, request.args]);
  if (state !== 'editing') return null;
  const asString = typeof request.args === 'string';
  const onChange = (value: string) => {
    setText(value);
    if (asString) return send({ type: 'SET_DRAFT', args: value });
    try {
      send({ type: 'SET_DRAFT', args: JSON.parse(value) });
    } catch {
      send({ type: 'SET_DRAFT', args: draft, valid: false });
    }
  };
  return (
    <div data-part="editor">
      <label htmlFor={id}>{label}</label>
      <textarea id={id} value={text} aria-invalid={!draftValid} onChange={(ev) => onChange(ev.target.value)} />
      {!draftValid && <p data-part="editor-error">This is not valid JSON yet.</p>}
      <div data-part="editor-actions">
        <button type="button" data-part="save-edit" disabled={!draftValid} onClick={() => send({ type: 'SAVE_EDIT' })}>
          {save}
        </button>
        <button type="button" data-part="cancel-edit" onClick={() => send({ type: 'CANCEL_EDIT' })}>
          {cancel}
        </button>
      </div>
    </div>
  );
}

/** Countdown surface for the auto-timeout. Renders nothing when expiry is absent. */
function Expiry({ children }: { children?: (msLeft: number) => React.ReactNode }) {
  const { deadline, state } = useApprovalGate();
  const [now, setNow] = React.useState(() => Date.now());
  React.useEffect(() => {
    if (deadline == null || state !== 'pending') return;
    setNow(Date.now());
    const i = setInterval(() => setNow(Date.now()), 1000);
    return () => clearInterval(i);
  }, [deadline, state]);
  if (deadline == null) return null;
  const msLeft = Math.max(0, deadline - now);
  return (
    <div data-part="expiry" data-state={state} aria-live="polite">
      {children ? children(msLeft) : `${Math.ceil(msLeft / 1000)}s`}
    </div>
  );
}

const outcomeLabel: Record<ApprovalOutcome, string> = { granted: 'Granted', denied: 'Denied', expired: 'Expired' };

/** "Verified" only once the host passes serverReceiptId; before that the record is local. */
export function receiptStatus(d: ApprovalDecision): 'Verified' | 'Recorded on this device' {
  return d.serverReceiptId ? 'Verified' : 'Recorded on this device';
}

export function receiptText(d: ApprovalDecision, revocation: ApprovalRevocation | null = null): string {
  if (revocation) return `Revoked. The grant for version ${d.requestVersion} no longer applies.`;
  const scope = d.outcome === 'granted' ? `, ${scopeLabel[d.scope]}` : '';
  const edited = d.editedArgs !== undefined ? ' with your edit' : '';
  return `${outcomeLabel[d.outcome]}${scope}, for version ${d.requestVersion}${edited}. ${receiptStatus(d)}.`;
}

/** Post-decision record. Renders only after the gate settles. */
function Receipt({ children }: { children?: (d: ApprovalDecision, revocation: ApprovalRevocation | null) => React.ReactNode }) {
  const { decision, revocation, state } = useApprovalGate();
  if (!decision || !isSettled(state)) return null;
  return (
    <div
      data-part="receipt"
      data-state={state}
      data-verified={decision.serverReceiptId ? 'true' : 'false'}
      aria-live="polite"
    >
      {children ? (
        children(decision, revocation)
      ) : (
        <>
          {receiptText(decision, revocation)} <time dateTime={decision.decidedAt}>{decision.decidedAt}</time>
        </>
      )}
    </div>
  );
}

/** Withdraws a grant. Renders only while granted. */
function Revoke(props: TriggerProps) {
  const { state, send } = useApprovalGate();
  if (state !== 'granted') return null;
  return <button type="button" data-part="revoke" onClick={() => send({ type: 'REVOKE' })} {...props} />;
}

export function changedText(old: ApprovalDecision, current: ActionRequest): string {
  return `The agent changed the request after your decision. That decision covered version ${old.requestVersion} and does not apply to version ${current.version}.`;
}

/** Shown when a new request version replaced an earlier decision. */
function Changed({ children }: { children?: (old: ApprovalDecision, current: ActionRequest) => React.ReactNode }) {
  const { superseded, request, state } = useApprovalGate();
  if (!superseded || isSettled(state)) return null;
  return (
    <div data-part="changed" role="status">
      {children ? children(superseded, request) : changedText(superseded, request)}
    </div>
  );
}

export const ApprovalGate = Object.assign(Root, {
  Preview,
  Details,
  Scope,
  Approve,
  Reject,
  Edit,
  Editor,
  Expiry,
  Receipt,
  Revoke,
  Changed,
});

/**
 * ApprovalGate — styled reference implementation with vendor presets.
 * Presets are descriptive recreations mined from official docs for comparison —
 * never vendor assets or copied proprietary styling. Label them "recreation".
 */
import * as React from 'react';
import {
  ApprovalGate as Core,
  type ActionRequest,
  type ApprovalDecision,
  type ApprovalGateConfig,
  type ApprovalRevocation,
} from './approval-gate-core';
import type { InteractionEventHandler } from '@/lib/interaction-contract';

export interface ApprovalGatePreset {
  id: string;
  label: string;
  copy: {
    title: string;
    approve: string;
    reject: string;
    edit?: string;
    revoke?: string;
  };
  machineConfig: Partial<ApprovalGateConfig>;
}

export const presets: Record<'neutral' | 'anthropic' | 'openai', ApprovalGatePreset> = {
  neutral: {
    id: 'neutral',
    label: 'Neutral',
    copy: { title: 'Approval required', approve: 'Approve', reject: 'Reject', edit: 'Edit', revoke: 'Revoke' },
    machineConfig: { scopes: ['once', 'session', 'standing'], defaultScope: 'once', expiresInMs: null, allowEdit: true },
  },
  anthropic: {
    id: 'anthropic',
    label: 'Claude Code (recreation)',
    copy: {
      title: 'Claude wants to run',
      approve: 'Yes',
      reject: "No, tell Claude what to do differently",
      edit: undefined, // redirect via reply, not in-place edit
      revoke: 'Remove rule',
    },
    // Scope is a first-class editable object: once / session / always rules
    machineConfig: { scopes: ['once', 'session', 'standing'], defaultScope: 'once', expiresInMs: null, allowEdit: false },
  },
  openai: {
    id: 'openai',
    label: 'Codex (recreation)',
    copy: { title: 'Codex requests approval', approve: 'Approve', reject: 'Deny' },
    // Mode-based: per-command approval, no persistent rule editing, no revoke
    machineConfig: { scopes: ['once', 'session'], defaultScope: 'once', expiresInMs: null, allowEdit: false },
  },
};

export interface ApprovalGateProps {
  preset?: keyof typeof presets;
  /** The action the agent asks to take. Send a new version whenever it changes. */
  request: ActionRequest;
  /** Overrides the preset's machine config, e.g. a shorter expiry. */
  config?: Partial<ApprovalGateConfig>;
  /** Called once per decision. Verify it server-side, then pass back serverReceiptId. */
  onDecision?: (d: ApprovalDecision) => void;
  onRevoke?: (r: ApprovalRevocation) => void;
  /** The id your server returned after storing the decision. The receipt reads "Verified" once set. */
  serverReceiptId?: string;
  /** One agent run; stamped on every contract event. */
  runId?: string;
  /** Interaction Contract events (see the Interaction Contract docs page). */
  onEvent?: InteractionEventHandler;
  /** Carried on every approval.* event. Pass the plan id so the approval points at the plan. */
  correlationId?: string;
}

export function ApprovalGate({
  preset = 'neutral',
  request,
  config,
  onDecision,
  onRevoke,
  serverReceiptId,
  runId,
  onEvent,
  correlationId,
}: ApprovalGateProps) {
  const p = presets[preset];
  const machineConfig = React.useMemo(() => ({ ...p.machineConfig, ...config }), [p, config]);
  return (
    <Core
      request={request}
      config={machineConfig}
      onDecision={onDecision}
      onRevoke={onRevoke}
      serverReceiptId={serverReceiptId}
      runId={runId}
      onEvent={onEvent}
      correlationId={correlationId}
    >
      <div className="ah-approval" data-preset={p.id}>
        <p style={{ margin: '0 0 .5rem', fontSize: '.75rem', textTransform: 'uppercase', letterSpacing: '.08em', opacity: 0.6 }}>
          {p.copy.title}
        </p>
        <Core.Changed />
        <Core.Preview />
        <Core.Details />
        <Core.Editor />
        <Core.Scope />
        <div className="ah-actions">
          <Core.Approve>{p.copy.approve}</Core.Approve>
          <Core.Reject>{p.copy.reject}</Core.Reject>
          {p.copy.edit && <Core.Edit>{p.copy.edit}</Core.Edit>}
          {p.copy.revoke && <Core.Revoke>{p.copy.revoke}</Core.Revoke>}
          <Core.Expiry />
        </div>
        <Core.Receipt />
      </div>
    </Core>
  );
}