Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

9.2 KB
Raw Blame
import type { TokenUsage } from '@/lib/actions/protocol';
import { isClockTime, isWeekday, nextAfter, type ScheduleRule, type Weekday } from './rule';

export const MAX_TASKS = 25;
export const MIN_EVERY_MINUTES = 5;
export const MAX_EVERY_MINUTES = 7 * 24 * 60;
export const MAX_TIMES_PER_DAY = 12;
export const MAX_RUNS_KEPT = 20;
export const MAX_TASK_RUNS = 1_000;
export const MAX_TASK_NAME = 80;
export const MAX_INSTRUCTION_CHARS = 2_000;
export const MAX_VARIABLES = 20;
export const MAX_VARIABLE_CHARS = 200;
export const MAX_HEADLINE_CHARS = 240;
export const TASK_APPROVAL_WAIT_MS = 10 * 60_000;
export const TASK_RUN_MAX_MS = 20 * 60_000;

export type TaskJob =
  | { kind: 'instruction'; text: string }
  | { kind: 'recording'; recordingId: string; name: string; variables?: Record<string, string> };

export type MissedPolicy = 'runOnce' | 'skip';

export type NotifyPolicy = 'always' | 'failure' | 'never';

export type RunOutcome = 'ok' | 'failed' | 'missed' | 'skipped' | 'cancelled';

export interface TaskRun {
  at: number;
  /** Which dispatch this was, so a report that arrives after the daemon gave up replaces that entry. */
  runId?: string;
  outcome: RunOutcome;
  reason?: string;
  headline?: string;
  durationMs?: number;
  usage?: TokenUsage;
  sessionId?: string;
}

export interface TaskDraft {
  id?: string;
  name: string;
  job: TaskJob;
  url: string;
  browser?: string;
  rule: ScheduleRule;
  missed: MissedPolicy;
  notify: NotifyPolicy;
  keepTab: boolean;
  maxRuns?: number;
  until?: number;
  enabled: boolean;
}

export interface ScheduledTask extends Omit<TaskDraft, 'id'> {
  id: string;
  nextRunAt: number | null;
  createdAt: number;
  runCount: number;
  runs: TaskRun[];
}

export interface TaskList {
  paused: boolean;
  tasks: ScheduledTask[];
  running: Record<string, number>;
}

export interface TaskOrder {
  id: string;
  runId: string;
  name: string;
  job: TaskJob;
  url: string;
  keepTab: boolean;
  notify: NotifyPolicy;
  previous?: string;
}

export interface TaskContext {
  id: string;
  name: string;
  previous?: string;
}

export type TaskResult = Omit<TaskRun, 'at'>;

export const EMPTY_TASK_LIST: TaskList = { paused: false, tasks: [], running: {} };

export type TaskValidation = { ok: true; draft: TaskDraft } | { ok: false; field: string; message: string };

const MISSED: readonly MissedPolicy[] = ['runOnce', 'skip'];
const NOTIFY: readonly NotifyPolicy[] = ['always', 'failure', 'never'];

const invalid = (field: string, message: string): TaskValidation => ({ ok: false, field, message });

const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;

function isWebUrl(value: unknown): value is string {
  if (typeof value !== 'string') return false;
  try {
    return ['http:', 'https:'].includes(new URL(value).protocol);
  } catch {
    return false;
  }
}

function checkJob(raw: unknown): TaskJob | string {
  if (!isRecord(raw)) return 'Say what the task should do.';
  if (raw.kind === 'instruction') {
    const text = typeof raw.text === 'string' ? raw.text.trim() : '';
    if (!text) return 'Write the instruction the agent should follow.';
    if (text.length > MAX_INSTRUCTION_CHARS) return `Keep the instruction under ${MAX_INSTRUCTION_CHARS} characters.`;
    return { kind: 'instruction', text };
  }
  if (raw.kind === 'recording') {
    if (typeof raw.recordingId !== 'string' || !raw.recordingId) return 'Pick the recording to replay.';
    const name = typeof raw.name === 'string' ? raw.name.trim().slice(0, MAX_TASK_NAME) : '';
    const entries = isRecord(raw.variables) ? Object.entries(raw.variables) : [];
    if (entries.length > MAX_VARIABLES) return `A recording takes at most ${MAX_VARIABLES} values.`;
    if (entries.some(([, value]) => typeof value !== 'string' || value.length > MAX_VARIABLE_CHARS)) {
      return `Each value the recording needs is text of at most ${MAX_VARIABLE_CHARS} characters.`;
    }
    const variables = Object.fromEntries(entries) as Record<string, string>;
    return { kind: 'recording', recordingId: raw.recordingId, name, ...(entries.length ? { variables } : {}) };
  }
  return 'A task either follows an instruction or replays a recording.';
}

/** A time already in the past is refused only when it is new: a task that has had its day can still be renamed or switched off. */
export function validateRule(raw: unknown, now: number, stored?: ScheduleRule): ScheduleRule | string {
  if (!isRecord(raw)) return 'Say when the task should run.';
  if (raw.kind === 'once') {
    if (typeof raw.at !== 'number' || !Number.isFinite(raw.at)) return 'Pick the date and time to run it.';
    const kept = stored?.kind === 'once' && stored.at === raw.at;
    if (raw.at <= now && !kept) return 'That time has already passed.';
    return { kind: 'once', at: raw.at };
  }
  if (raw.kind === 'every') {
    const minutes = raw.minutes;
    if (typeof minutes !== 'number' || !Number.isInteger(minutes)) return 'Say how often to repeat it.';
    if (minutes < MIN_EVERY_MINUTES) return `Repeat it at most every ${MIN_EVERY_MINUTES} minutes.`;
    if (minutes > MAX_EVERY_MINUTES) return 'Repeat it at least once a week.';
    if (raw.window === undefined) return { kind: 'every', minutes };
    const window = raw.window;
    if (!isRecord(window) || !isClockTime(window.from) || !isClockTime(window.to)) {
      return 'Give the window as two times, like 08:00 and 22:00.';
    }
    if (window.from === window.to) return 'The window has to start and end at different times.';
    return { kind: 'every', minutes, window: { from: window.from, to: window.to } };
  }
  if (raw.kind === 'weekly') {
    const days = Array.isArray(raw.days) ? [...new Set(raw.days)] : [];
    if (!days.length || !days.every(isWeekday)) return 'Pick at least one day.';
    const times = Array.isArray(raw.times) ? [...new Set(raw.times)] : [];
    if (!times.length || !times.every(isClockTime)) return 'Give at least one time, like 09:00.';
    if (times.length > MAX_TIMES_PER_DAY) return `Pick at most ${MAX_TIMES_PER_DAY} times a day.`;
    return { kind: 'weekly', days: (days as Weekday[]).sort(), times: (times as string[]).sort() };
  }
  return 'A task runs once, every so often, or on set days.';
}

export function validateTask(input: unknown, now: number, stored?: Pick<ScheduledTask, 'rule' | 'until'>): TaskValidation {
  if (!isRecord(input)) return invalid('task', 'Nothing to save.');

  const name = typeof input.name === 'string' ? input.name.trim() : '';
  if (!name) return invalid('name', 'Give the task a name.');
  if (name.length > MAX_TASK_NAME) return invalid('name', `Keep the name under ${MAX_TASK_NAME} characters.`);

  const job = checkJob(input.job);
  if (typeof job === 'string') return invalid('job', job);

  if (!isWebUrl(input.url)) return invalid('url', 'Start it on a web page — an http or https address.');

  const rule = validateRule(input.rule, now, stored?.rule);
  if (typeof rule === 'string') return invalid('rule', rule);

  const missed = MISSED.includes(input.missed as MissedPolicy) ? (input.missed as MissedPolicy) : 'runOnce';
  const notify = NOTIFY.includes(input.notify as NotifyPolicy) ? (input.notify as NotifyPolicy) : 'always';

  const maxRuns = input.maxRuns;
  if (maxRuns !== undefined && (typeof maxRuns !== 'number' || !Number.isInteger(maxRuns) || maxRuns < 1 || maxRuns > MAX_TASK_RUNS)) {
    return invalid('maxRuns', `Stop after between 1 and ${MAX_TASK_RUNS} runs.`);
  }
  const until = input.until;
  if (until !== undefined && (typeof until !== 'number' || (until <= now && until !== stored?.until))) {
    return invalid('until', 'The end date has already passed.');
  }
  if (input.browser !== undefined && typeof input.browser !== 'string') return invalid('browser', 'Pick a browser.');

  return {
    ok: true,
    draft: {
      ...(typeof input.id === 'string' && input.id ? { id: input.id } : {}),
      name,
      job,
      url: input.url,
      ...(typeof input.browser === 'string' && input.browser ? { browser: input.browser } : {}),
      rule,
      missed,
      notify,
      keepTab: input.keepTab === true,
      ...(maxRuns !== undefined ? { maxRuns } : {}),
      ...(until !== undefined ? { until } : {}),
      enabled: input.enabled !== false,
    },
  };
}

export function nextRunFor(
  task: Pick<ScheduledTask, 'rule' | 'enabled' | 'until' | 'maxRuns' | 'runCount'>,
  after: number,
): number | null {
  if (!task.enabled) return null;
  if (task.maxRuns !== undefined && task.runCount >= task.maxRuns) return null;
  const next = nextAfter(task.rule, after);
  if (next === null) return null;
  return task.until !== undefined && next > task.until ? null : next;
}

export const orderFor = (task: ScheduledTask, runId: string): TaskOrder => ({
  id: task.id,
  runId,
  name: task.name,
  job: task.job,
  url: task.url,
  keepTab: task.keepTab,
  notify: task.notify,
  previous: task.runs.find((run) => run.outcome === 'ok' && run.headline)?.headline,
});

export function headlineOf(text: string): string | undefined {
  const lines = text
    .split('\n')
    .map((line) => line.replace(/^\s*(?:[#>]+|[-*+]|\d+\.)\s+/, '').replace(/\*\*|__|`/g, '').trim())
    .filter(Boolean);
  const last = lines.at(-1);
  if (!last) return undefined;
  return last.length > MAX_HEADLINE_CHARS ? `${last.slice(0, MAX_HEADLINE_CHARS - 1)}…` : last;
}