@ruakit/agent 0.0.0-stage → 0.1.0-alpha.1

package/src/request-state.ts

@@ -0,0 +1,189 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { REQUEST_MESSAGES } from './constants.js';
+import type { Clarification, ExecutionResult } from "@ruakit/schema";
+import type { RequestError, RequestIdentity } from "./request-outcome.js";
+import type { ApprovalRequest } from "./approval.js";
+
+/** Machine-readable execution stages; progress messages remain separate UI text. */
+export type RequestPhase = "observing" | "planning" | "executing";
+
+interface ActiveRequest {
+  requestId: number;
+  message: string;
+  identity?: RequestIdentity;
+}
+
+export type RequestState =
+  | { status: "idle"; message: string }
+  | (ActiveRequest & { status: "running" | "cancelling"; phase: RequestPhase })
+  | (ActiveRequest & {
+      status: "approval";
+      approvalId: string;
+      approval: ApprovalRequest;
+      originalPrompt: string;
+    })
+  | (ActiveRequest & { status: "triggered"; result: ExecutionResult })
+  | (ActiveRequest & {
+      status: "clarification";
+      clarification: Clarification;
+      originalPrompt: string;
+    })
+  | (ActiveRequest & { status: "cancelled" })
+  | (ActiveRequest & { status: "failed"; error?: RequestError });
+
+export type RequestEvent =
+  | { type: "started"; requestId: number; identity?: RequestIdentity }
+  | { type: "progress"; requestId: number; message: string }
+  | { type: "phase"; requestId: number; phase: RequestPhase }
+  | {
+      type: "approval";
+      requestId: number;
+      approvalId: string;
+      approval: ApprovalRequest;
+      originalPrompt: string;
+    }
+  | { type: "approval-resolved"; requestId: number }
+  | {
+      type: "cancelling" | "cancelled";
+      requestId: number;
+    }
+  | { type: "triggered"; requestId: number; result: ExecutionResult }
+  | { type: "failed"; requestId: number; message: string; error?: RequestError }
+  | {
+      type: "clarification";
+      requestId: number;
+      clarification: Clarification;
+      originalPrompt: string;
+      message?: string;
+    }
+  | { type: "reset" };
+
+export const INITIAL_REQUEST_STATE: RequestState = Object.freeze({
+  status: "idle",
+  message: REQUEST_MESSAGES.ready,
+});
+
+export function requestIsBusy(
+  state: RequestState,
+): state is Extract<
+  RequestState,
+  { status: "running" | "cancelling" | "approval" }
+> {
+  return (
+    state.status === "running" ||
+    state.status === "cancelling" ||
+    state.status === "approval"
+  );
+}
+
+/** Ignore obsolete completions and progress after cancellation or settlement. */
+export function requestReducer(
+  state: RequestState,
+  event: RequestEvent,
+): RequestState {
+  if (event.type === "reset") {
+    return requestIsBusy(state) ? state : INITIAL_REQUEST_STATE;
+  }
+  if (event.type === "started") {
+    return requestIsBusy(state)
+      ? state
+      : {
+          status: "running",
+          requestId: event.requestId,
+          ...(event.identity ? { identity: event.identity } : {}),
+          phase: "observing",
+          message: REQUEST_MESSAGES.thinking,
+        };
+  }
+  const cancellingQuestion =
+    state.status === "clarification" && event.type === "cancelled";
+  if (cancellingQuestion && state.requestId === event.requestId) {
+    return {
+      status: "cancelled",
+      requestId: state.requestId,
+      ...(state.identity ? { identity: state.identity } : {}),
+      message: REQUEST_MESSAGES.cancelled,
+    };
+  }
+  if (!requestIsBusy(state) || state.requestId !== event.requestId) {
+    return state;
+  }
+  const identity = state.identity ? { identity: state.identity } : {};
+  switch (event.type) {
+    case "progress":
+      return state.status === "running"
+        ? { ...state, message: event.message }
+        : state;
+    case "phase":
+      return state.status === "running"
+        ? { ...state, phase: event.phase }
+        : state;
+    case "approval":
+      return state.status === "cancelling"
+        ? state
+        : {
+            status: "approval",
+            ...identity,
+            requestId: event.requestId,
+            approvalId: event.approvalId,
+            approval: event.approval,
+            originalPrompt: event.originalPrompt,
+            message: event.approval.message,
+          };
+    case "approval-resolved":
+      return state.status !== "approval"
+        ? state
+        : {
+            status: "running",
+            ...identity,
+            requestId: event.requestId,
+            phase: "executing",
+            message: REQUEST_MESSAGES.checkingApproval,
+          };
+    case "cancelling":
+      return {
+        ...state,
+        status: "cancelling",
+        phase: state.status === "approval" ? "executing" : state.phase,
+        message: REQUEST_MESSAGES.cancelling,
+      };
+    case "cancelled":
+      return {
+        status: "cancelled",
+        ...identity,
+        requestId: event.requestId,
+        message: REQUEST_MESSAGES.cancelled,
+      };
+    case "triggered":
+      return state.status === "cancelling"
+        ? state
+        : {
+            status: "triggered",
+            ...identity,
+            requestId: event.requestId,
+            result: event.result,
+            message: event.result.message ?? REQUEST_MESSAGES.triggered,
+          };
+    case "clarification":
+      return state.status === "cancelling"
+        ? state
+        : {
+            status: "clarification",
+            ...identity,
+            requestId: event.requestId,
+            clarification: event.clarification,
+            originalPrompt: event.originalPrompt,
+            message: event.message ?? event.clarification.question,
+          };
+    case "failed":
+      return state.status === "cancelling"
+        ? state
+        : {
+            status: "failed",
+            ...identity,
+            ...(event.error ? { error: event.error } : {}),
+            requestId: event.requestId,
+            message: event.message,
+          };
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,88 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { RUNTIME_META_NAME } from '@ruakit/schema';
+import type { ClarificationTurn, ExecutionResult } from '@ruakit/schema';
+import { RuaKitError } from './errors.js';
+import { createDecisionRuntime } from './decision-runtime.js';
+import type { ExecutionOptions, RuaSession } from './session.js';
+import { createHttpTransport } from './transport.js';
+import { createPlanTransport } from './plan-transport.js';
+import type { PlanTransport } from './plan-transport.js';
+import type { PlanPlanner, PlanTask, PlanTaskOptions } from './plan.js';
+import { createSession } from './session.js';
+import type { HttpTransportOptions, RuaKitTransport } from './transport.js';
+
+export interface RuntimeOptions extends HttpTransportOptions, Omit<ExecutionOptions, 'signal'> {
+  protocol?: 'decision';
+  document?: Document;
+  /** Reuse the target registry used by snapshot/run primitives. */
+  session?: RuaSession;
+  transport?: RuaKitTransport;
+}
+export interface PlanRuntimeOptions extends Omit<RuntimeOptions, 'transport' | 'protocol'>,
+  Pick<PlanTaskOptions, 'context' | 'maxReplans' | 'onPlan'> {
+  protocol: 'plan';
+  transport?: PlanTransport;
+  planner?: PlanPlanner;
+  task?: PlanTask;
+}
+
+export interface RequestOptions {
+  signal?: AbortSignal;
+  clarifications?: ClarificationTurn[];
+}
+
+export interface RuaKitRuntime {
+  request(prompt: string, options?: RequestOptions): Promise<ExecutionResult>;
+}
+
+/** Plan from the rendered page and execute only locally observed DOM targets. */
+export function createRuntime(options?: RuntimeOptions): RuaKitRuntime;
+export function createRuntime(options: PlanRuntimeOptions): RuaKitRuntime;
+export function createRuntime(options: RuntimeOptions | PlanRuntimeOptions = {}): RuaKitRuntime {
+  const document = options.document ?? options.session?.document ?? globalThis.document;
+  if (!document?.defaultView) {
+    throw new RuaKitError('UNAVAILABLE', 'RuaKit requires a browser document.');
+  }
+  const embedded = document.querySelector<HTMLMetaElement>(
+    `meta[name="${RUNTIME_META_NAME}"]`,
+  )?.content;
+  let serverUrl: string | undefined;
+  if (embedded !== undefined) {
+    try {
+      const value: unknown = JSON.parse(embedded);
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error();
+      }
+      const record = value as Record<string, unknown>;
+      if (
+        record.serverUrl !== undefined &&
+        (typeof record.serverUrl !== 'string' || !record.serverUrl.trim())
+      ) {
+        throw new Error();
+      }
+      serverUrl = record.serverUrl as string | undefined;
+    } catch {
+      throw new RuaKitError('INVALID_REQUEST', 'The page has invalid RuaKit configuration.');
+    }
+  }
+  if (options.protocol === 'plan') {
+    const session = options.session ?? createSession({ document });
+    if (session.document !== document)
+      throw new RuaKitError('INVALID_REQUEST', 'The Rua session belongs to a different document.');
+    const transport = options.planner ? undefined : options.transport ?? createPlanTransport({
+      ...options, ...(options.serverUrl === undefined && serverUrl ? { serverUrl } : {}), document,
+    });
+    return {
+      request: (prompt, settings = {}) => (options.task ?? session.createPlanTask()).request(prompt,
+        options.planner ?? ((input, signal) => transport!.plan(input, signal)), { ...options, ...settings }),
+    };
+  }
+  return createDecisionRuntime(
+    options,
+    options.transport ??
+      createHttpTransport({
+        ...options,
+        ...(options.serverUrl === undefined && serverUrl ? { serverUrl } : {}),
+      }),
+  );
+}

package/src/session.ts

@@ -0,0 +1,408 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { REQUEST_MESSAGES } from './constants.js';
+import { createRuntime as createDomRuntime } from '@ruakit/runtime';
+import type { ActionFeedbackOptions, PageState, Screenshot } from '@ruakit/runtime';
+import {
+  completionChecksSchema,
+  evaluateCompletionChecks,
+  decisionSchema,
+  decisionRequestSchema,
+} from '@ruakit/schema';
+import type {
+  ClarificationTurn,
+  CompletionCheck,
+  ExecutionResult,
+  Decision,
+} from '@ruakit/schema';
+import { ClarificationNeededError, RuaKitError, parsePayload } from './errors.js';
+import { createRequestOperation, runWithSignal, validateRequestTimeout } from './operations.js';
+import type { RequestPhase } from './request-state.js';
+import type { RuaKitTransport } from './transport.js';
+import { executePlan, createPlanTask } from './plan.js';
+import { requestApproval } from './approval.js';
+import type { ApprovalOptions } from './approval.js';
+import type { PlanExecutionOptions, PlanExecutionResult, PlanTask, PlanEngine } from './plan.js';
+
+export interface ExecutionOptions extends ActionFeedbackOptions, ApprovalOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  requestTimeoutMs?: number;
+  /** Optional stronger application check, called only after all DOM outcomes pass. */
+  verifyCompletion?: (context: CompletionContext) => boolean | Promise<boolean>;
+  /** Observational feedback; exceptions cannot change execution. */
+  onProgress?: (message: string) => void;
+  onPhaseChange?: (phase: RequestPhase) => void;
+}
+
+export interface CompletionContext {
+  prompt: string | undefined;
+  checks: readonly CompletionCheck[];
+  baseline: PageState;
+  snapshot: PageState;
+  signal: AbortSignal;
+}
+
+export interface RunOptions extends ExecutionOptions {
+  /** The original observation used to obtain this decision, from this session. */
+  snapshot: PageState;
+  /** Optional host-established outcomes for a manually owned loop. */
+  checks?: CompletionCheck[];
+  /** Original session observation for checks requiring a newly appeared result. */
+  baseline?: PageState;
+}
+
+export interface PlanOptions extends ExecutionOptions {
+  clarifications?: ClarificationTurn[];
+}
+
+export interface RuaSession {
+  readonly document: Document;
+  snapshot(): PageState;
+  /** Validate and apply one decision. A triggered action does not establish task completion. */
+  run(decision: unknown, options: RunOptions): Promise<ExecutionResult>;
+  executePlan(plan: unknown, options?: PlanExecutionOptions): Promise<PlanExecutionResult>;
+  createPlanTask(): PlanTask;
+  /** Observe, request a decision, and apply it until the planner finishes or asks a question. */
+  plan(
+    prompt: string,
+    request: RuaKitTransport['dom'],
+    options?: PlanOptions,
+  ): Promise<ExecutionResult>;
+}
+
+/** One browser target registry shared by observation, execution, and planning. */
+export function createSession(options: { document?: Document } = {}): RuaSession {
+  const document = options.document ?? globalThis.document;
+  if (!document?.defaultView) {
+    throw new RuaKitError('UNAVAILABLE', 'RuaKit requires a browser document.');
+  }
+  let active: ExecutionOptions | undefined;
+  let busy = false;
+  let currentSignal: AbortSignal | undefined;
+  let settled: Promise<void> | undefined;
+  let sequence = 0;
+  const observations = new WeakMap<PageState, PageState>();
+  const baselines = new WeakMap<PageState, PageState>();
+  const dom = createDomRuntime({
+    root: document,
+    timeoutMs: 8000,
+    onAction: (event) => active?.onAction?.(event),
+    get actionDelayMs() {
+      return active?.actionDelayMs ?? 0;
+    },
+    get scrollToTarget() {
+      return active?.scrollToTarget ?? false;
+    },
+  });
+
+  function snapshot(): PageState {
+    const state = dom.getState();
+    // Keep our own copy so callers cannot authorize targets by editing a snapshot.
+    const original = structuredClone(state);
+    observations.set(state, original);
+    baselines.set(state, original);
+    return state;
+  }
+
+  function notify(settings: ExecutionOptions, message: string): void {
+    try {
+      settings.onProgress?.(message);
+    } catch {
+      /* Feedback is observational. */
+    }
+  }
+
+  function phase(settings: ExecutionOptions, value: RequestPhase): void {
+    try {
+      settings.onPhaseChange?.(value);
+    } catch {
+      /* Feedback is observational. */
+    }
+  }
+
+  async function own<T>(
+    settings: ExecutionOptions,
+    perform: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
+    if (busy) {
+      // React Strict Mode can start a replacement before the cancelled call's
+      // finally block runs. Wait for that owner rather than overlapping actions.
+      if (currentSignal?.aborted) {
+        await settled;
+        return own(settings, perform);
+      }
+      throw new RuaKitError('BUSY', 'A RuaKit request is already running.');
+    }
+    busy = true;
+    let release!: () => void;
+    settled = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    try {
+      validateRequestTimeout(settings.timeoutMs ?? 8000);
+      const operation = createRequestOperation(settings.requestTimeoutMs ?? 60000, settings.signal);
+      currentSignal = operation.signal;
+      active = settings;
+      try {
+        operation.signal.throwIfAborted();
+        return await perform(operation.signal);
+      } finally {
+        operation.dispose();
+      }
+    } finally {
+      active = undefined;
+      currentSignal = undefined;
+      busy = false;
+      release();
+    }
+  }
+
+  function receipt(
+    events: string[],
+    decision: Decision,
+    level: 'observed' | 'confirmed' = 'observed',
+  ): ExecutionResult {
+    return {
+      planId: `dom-${Date.now()}-${++sequence}`,
+      status: 'triggered',
+      events,
+      ...(decision.type === 'complete'
+        ? {
+            goalCompleted: true as const,
+            message: decision.message,
+            verification: { level, checks: decision.checks },
+          }
+        : {}),
+    };
+  }
+
+  async function apply(
+    value: unknown,
+    source: PageState,
+    signal: AbortSignal,
+    settings: ExecutionOptions,
+    verification?: {
+      baseline: PageState;
+      checks: CompletionCheck[] | undefined;
+      prompt: string | undefined;
+      requirePreparation?: boolean;
+    },
+  ): Promise<Decision> {
+    signal.throwIfAborted();
+    const observed = observations.get(source);
+    if (!observed) {
+      throw new RuaKitError('INVALID_PLAN', 'Use an unused snapshot from this Rua session.');
+    }
+    const decision = parsePayload(
+      decisionSchema,
+      value,
+      'INVALID_PLAN',
+      'The planner returned an invalid decision.',
+    );
+    observations.delete(source);
+    notify(settings, decision.message);
+    signal.throwIfAborted();
+    if (decision.type === 'clarify') {
+      throw new ClarificationNeededError({
+        type: 'clarification',
+        question: decision.message,
+        options: [],
+      });
+    }
+    if (decision.type === 'unsupported') {
+      throw new RuaKitError('UNAVAILABLE', decision.message);
+    }
+    if (decision.type === 'complete') {
+      const checks = verification?.checks ?? decision.checks;
+      if (JSON.stringify(checks) !== JSON.stringify(decision.checks)) {
+        throw new RuaKitError(
+          'INVALID_PLAN',
+          'Completion checks cannot change after execution begins.',
+        );
+      }
+      const baseline = verification?.baseline ?? observed;
+      if (
+        !evaluateCompletionChecks(checks, observed, baseline).passed ||
+        !evaluateCompletionChecks(checks, dom.getState(), baseline).passed
+      ) {
+        throw new RuaKitError(
+          'INVALID_PLAN',
+          'The requested outcomes are not all present on the live page.',
+        );
+      }
+      if (settings.verifyCompletion) {
+        const confirmed = await runWithSignal(signal, () =>
+          settings.verifyCompletion!({
+            prompt: verification?.prompt,
+            checks: structuredClone(checks),
+            baseline: structuredClone(baseline),
+            snapshot: dom.getState(),
+            signal,
+          }),
+        );
+        signal.throwIfAborted();
+        if (confirmed !== true)
+          throw new RuaKitError(
+            'VERIFICATION_FAILED',
+            'The application could not confirm the requested outcome.',
+          );
+        if (!evaluateCompletionChecks(checks, dom.getState(), baseline).passed) {
+          throw new RuaKitError(
+            'INVALID_PLAN',
+            'The page changed while the application verified completion.',
+          );
+        }
+      }
+      return decision;
+    }
+    if (decision.type === 'prepare' || decision.type === 'screenshot') return decision;
+    if (verification?.requirePreparation && !verification.checks) {
+      throw new RuaKitError(
+        'INVALID_PLAN',
+        'Establish completion checks with prepare before taking actions.',
+      );
+    }
+    const step = decision.step;
+    const control = observed.controls.find(
+      (item) => item.target.id === step.target.id && item.target.version === step.target.version,
+    );
+    if (!control || !control.enabled) {
+      throw new RuaKitError('INVALID_PLAN', 'The planner selected an unavailable live DOM target.');
+    }
+    if (decision.type === 'approval') {
+      await requestApproval(decision, observed, signal, settings, verification?.prompt);
+    }
+    phase(settings, 'executing');
+    const action = { signal, timeoutMs: settings.timeoutMs ?? 8000 };
+    switch (step.type) {
+      case 'focus':
+        await dom.focus(step.target, action);
+        break;
+      case 'key':
+        await dom.pressKey(step.target, step.key, {
+          ...action,
+          altKey: step.altKey,
+          ctrlKey: step.ctrlKey,
+          metaKey: step.metaKey,
+          shiftKey: step.shiftKey,
+        });
+        break;
+      case 'insertText':
+        await dom.insertText(step.target, step.text, action);
+        break;
+      case 'click':
+        await dom.click(step.target, action);
+        break;
+      case 'fill':
+        await dom.setValue(step.target, step.value, action);
+        break;
+      case 'select':
+        await dom.selectOption(step.target, step.values, action);
+        break;
+      case 'check':
+        await dom.setChecked(step.target, step.checked, action);
+        break;
+    }
+    signal.throwIfAborted();
+    return decision;
+  }
+
+  const planEngine: PlanEngine = {
+    platform: document.defaultView?.navigator.platform ?? '',
+    snapshot, apply,
+    screenshot: (signal, timeoutMs) => dom.screenshot({ signal, timeoutMs }),
+  };
+
+  return {
+    document,
+    snapshot,
+    executePlan: (plan, options = {}) => own(options, (signal) => executePlan(planEngine, plan, signal, options)),
+    createPlanTask: () => createPlanTask(planEngine, own),
+    run: (decision, settings) =>
+      own(settings, async (signal) => {
+        const baseline = settings.baseline ? baselines.get(settings.baseline) : undefined;
+        if (settings.baseline && !baseline)
+          throw new RuaKitError(
+            'INVALID_PLAN',
+            'Use an original session observation as the verification baseline.',
+          );
+        const checks = settings.checks ? completionChecksSchema.parse(settings.checks) : undefined;
+        const applied = await apply(decision, settings.snapshot, signal, settings, {
+          baseline: baseline ?? observations.get(settings.snapshot) ?? settings.snapshot,
+          checks,
+          prompt: undefined,
+        });
+        const result = receipt(
+          [applied.message.slice(0, 500)],
+          applied,
+          settings.verifyCompletion ? 'confirmed' : 'observed',
+        );
+        if (applied.type === 'screenshot')
+          result.screenshot = await dom.screenshot({
+            signal,
+            timeoutMs: settings.timeoutMs ?? 8000,
+          });
+        return result;
+      }),
+    plan: (prompt, request, settings = {}) =>
+      own(settings, async (signal) => {
+        const history: Decision[] = [];
+        const events: string[] = [];
+        let checks: CompletionCheck[] | undefined;
+        let baseline: PageState | undefined;
+        let image: Screenshot | undefined;
+        notify(settings, REQUEST_MESSAGES.observing);
+        while (true) {
+          signal.throwIfAborted();
+          phase(settings, 'observing');
+          const source = snapshot();
+          baseline ??= structuredClone(source);
+          if (image && image.url !== source.url) image = undefined;
+          const input = parsePayload(
+            decisionRequestSchema,
+            {
+              platform: document.defaultView?.navigator.platform ?? '',
+              prompt,
+              clarifications: settings.clarifications ?? [],
+              snapshot: source,
+              history: history.slice(-20),
+              checks: checks ? structuredClone(checks) : null,
+              canScreenshot: true,
+              ...(image ? { screenshot: image } : {}),
+            },
+            'INVALID_REQUEST',
+            'Enter a valid request for the current application page.',
+          );
+          phase(settings, 'planning');
+          const decision = await apply(
+            await runWithSignal(signal, () => request(input, signal)),
+            source,
+            signal,
+            settings,
+            { baseline, checks, prompt, requirePreparation: true },
+          );
+          events.push(decision.message.slice(0, 500));
+          if (decision.type === 'complete') {
+            return receipt(events, decision, settings.verifyCompletion ? 'confirmed' : 'observed');
+          }
+          if (decision.type === 'prepare') {
+            if (checks)
+              throw new RuaKitError(
+                'INVALID_PLAN',
+                'Completion checks cannot change after preparation.',
+              );
+            checks = structuredClone(decision.checks);
+          }
+          if (decision.type === 'screenshot') {
+            if (image)
+              throw new RuaKitError(
+                'INVALID_PLAN',
+                'Use the supplied screenshot before requesting another image.',
+              );
+            image = await dom.screenshot({ signal, timeoutMs: settings.timeoutMs ?? 8000 });
+          } else image = undefined;
+          history.push(decision);
+        }
+      }),
+  };
+}