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

package/src/plan.ts

@@ -0,0 +1,177 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { z } from 'zod';
+import { decisionRequestSchema, actionSchema } from './decision.js';
+import {
+  completionChecksSchema,
+  controlLocatorSchema,
+} from './verification.js';
+
+/** Shared constraints for plan and step identifiers. */
+const identifier = z.string().trim().min(1).max(200);
+
+/** Fields added to each action when it becomes a planned step. */
+const metadata = {
+  id: identifier,
+  message: z.string().trim().min(1).max(2000),
+  target: controlLocatorSchema,
+};
+
+/** Resolve these locators against a fresh observation before executing each step. */
+export const plannedStepSchema = z.discriminatedUnion('type', [
+  actionSchema.options[0].extend(metadata),
+  actionSchema.options[1].extend(metadata),
+  actionSchema.options[2].extend(metadata),
+  actionSchema.options[3].extend(metadata),
+  actionSchema.options[4].extend(metadata),
+  actionSchema.options[5].extend(metadata),
+  actionSchema.options[6].extend(metadata),
+]);
+
+/** An ordered plan and the checks used to assess its outcome. */
+export const planSchema = z.strictObject({
+  id: identifier,
+  replacesPlanId: identifier.optional(),
+  message: z.string().trim().min(1).max(2000),
+  steps: z
+    .array(plannedStepSchema)
+    .max(50)
+    .refine(
+      (steps) => new Set(steps.map((step) => step.id)).size === steps.length,
+      'Plan step IDs must be distinct.',
+    ),
+  checks: completionChecksSchema,
+});
+
+/** Approval covers this concrete plan revision, including every action and argument. */
+export const planApprovalSchema = z.strictObject({
+  type: z.literal('approval'),
+  message: z.string().trim().min(1).max(2000),
+  plan: planSchema,
+});
+
+/** A step that has already been executed as part of a plan. */
+export const completedPlanStepSchema = z.strictObject({
+  planId: identifier,
+  step: plannedStepSchema,
+});
+
+/** Execution history and reason supplied when requesting a replacement plan. */
+export const replanSchema = z.strictObject({
+  planId: identifier,
+  completedSteps: z.array(completedPlanStepSchema).max(200),
+  failedStepId: identifier.nullable(),
+  reason: z.enum(['target-unavailable', 'target-stale', 'outcome-mismatch']),
+  message: z.string().min(1).max(2000),
+});
+
+/** JSON-compatible context accepted by the planning protocol. */
+export type JsonValue =
+  string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** Return the estimated size of a JSON primitive, or null for other values. */
+function primitiveSize(value: unknown): number | null {
+  if (value === null || typeof value === 'boolean') return 5;
+  if (typeof value === 'string') return value.length;
+  if (typeof value === 'number' && Number.isFinite(value)) return 24;
+  return null;
+}
+
+/** Accept arrays and plain objects, but not class instances or other objects. */
+function isJsonContainer(value: object): boolean {
+  if (Array.isArray(value)) return true;
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** Check that context is plain JSON within the protocol's traversal and size limits. */
+function boundedJson(value: unknown): value is JsonValue {
+  const maxNodes = 2048;
+  const maxDepth = 8;
+  const maxSize = 32768;
+
+  // Track pending values, visited objects, and the estimated serialized size.
+  const pending = [{ value, depth: 0 }];
+  const seen = new Set<object>();
+  let size = 0;
+  let nodes = 0;
+
+  while (pending.length > 0) {
+    const item = pending.pop()!;
+    const current = item.value;
+
+    nodes += 1;
+    if (nodes > maxNodes || item.depth > maxDepth) return false;
+
+    const estimatedSize = primitiveSize(current);
+    if (estimatedSize !== null) {
+      size += estimatedSize;
+    } else if (typeof current === 'object' && current !== null) {
+      // Repeated references, cycles, and non-plain objects are not accepted.
+      if (seen.has(current)) return false;
+      seen.add(current);
+      if (!isJsonContainer(current)) return false;
+
+      // Account for property names and visit their values at the next depth.
+      for (const [key, child] of Object.entries(current)) {
+        size += key.length + 4;
+        pending.push({ value: child, depth: item.depth + 1 });
+      }
+    } else {
+      return false;
+    }
+
+    if (size > maxSize) return false;
+  }
+
+  return true;
+}
+
+/** Context is JSON data, bounded independently of page observations and images. */
+export const planContextSchema = z.custom<JsonValue>(
+  boundedJson,
+  'Expected bounded JSON context.',
+);
+
+/** Request for a plan, optionally including application context and replan history. */
+export const planRequestSchema = decisionRequestSchema
+  .omit({ history: true })
+  .extend({
+    protocol: z.literal('plan'),
+    context: planContextSchema.optional(),
+    checks: completionChecksSchema.nullable(),
+    replan: replanSchema.nullable(),
+  });
+
+/** A plan or a response explaining what the planner needs next. */
+export const planResponseSchema = z.union([
+  planSchema,
+  planApprovalSchema,
+  z.strictObject({
+    type: z.literal('clarify'),
+    message: z.string().min(1).max(500),
+  }),
+  z.strictObject({
+    type: z.literal('screenshot'),
+    message: z.string().min(1).max(2000),
+  }),
+  z.strictObject({
+    type: z.literal('unsupported'),
+    message: z.string().min(1).max(2000),
+  }),
+]);
+
+/** A validated plan. */
+export type Plan = z.infer<typeof planSchema>;
+/** One action in a plan. */
+export type PlannedStep = z.infer<typeof plannedStepSchema>;
+/** A completed step and its originating plan. */
+export type CompletedPlanStep = z.infer<typeof completedPlanStepSchema>;
+/** The context for replacing a plan. */
+export type Replan = z.infer<typeof replanSchema>;
+/** A validated planning request. */
+export type PlanRequest = z.infer<typeof planRequestSchema>;
+/** A validated planning response. */
+export type PlanResponse = z.infer<typeof planResponseSchema>;
+/** A request to approve a concrete plan. */
+export type PlanApproval = z.infer<typeof planApprovalSchema>;

package/src/protocol.ts

@@ -0,0 +1,37 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { z } from 'zod';
+import type { DecisionRequest } from './decision.js';
+import { completionChecksSchema, screenshotSchema } from './verification.js';
+
+/** Name of the HTML metadata element used for runtime configuration. */
+export const RUNTIME_META_NAME = 'ruakit-config';
+
+/** A conversational response contains no executable instructions. */
+export const clarificationSchema = z.strictObject({
+  type: z.literal('clarification'),
+  question: z.string().trim().min(1).max(500),
+  options: z
+    .array(z.string().trim().min(1).max(400))
+    .max(4)
+    .refine((items) => new Set(items).size === items.length, 'Expected distinct options.'),
+});
+
+/** Result of an execution, including any observed verification evidence. */
+export const resultSchema = z.strictObject({
+  planId: z.string().min(1).max(200),
+  status: z.enum(['triggered', 'failed']),
+  events: z.array(z.string().max(500)).max(220),
+  goalCompleted: z.literal(true).optional(),
+  verification: z
+    .strictObject({ level: z.enum(['observed', 'confirmed']), checks: completionChecksSchema })
+    .optional(),
+  screenshot: screenshotSchema.optional(),
+  message: z.string().max(2000).optional(),
+});
+
+/** A question and optional choices returned to the user. */
+export type Clarification = z.infer<typeof clarificationSchema>;
+/** One question and answer included in a decision request. */
+export type ClarificationTurn = DecisionRequest['clarifications'][number];
+/** A validated execution result. */
+export type ExecutionResult = z.infer<typeof resultSchema>;

package/src/verification.ts

@@ -0,0 +1,204 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { z } from 'zod';
+
+/** Identifies a control by its observed identity and accessible context. */
+export const controlLocatorSchema = z.strictObject({
+  id: z.string().min(1).max(200).nullable(),
+  role: z.string().max(100),
+  label: z.string().max(1000),
+  context: z.string().max(1000).nullable(),
+  group: z.string().max(200).nullable(),
+});
+
+/** Reuse the same locator constraints for all control checks. */
+const locator = controlLocatorSchema;
+
+/** Human-readable explanation of the outcome being checked. */
+const description = z.string().trim().min(1).max(500);
+
+/** A single observable condition that can establish progress toward a goal. */
+export const completionCheckSchema = z.discriminatedUnion('type', [
+  z.strictObject({
+    type: z.literal('value'),
+    description,
+    control: locator,
+    equals: z.string().max(20000),
+  }),
+  z.strictObject({
+    type: z.literal('checked'),
+    description,
+    control: locator,
+    equals: z.boolean(),
+  }),
+  z.strictObject({
+    type: z.literal('selected'),
+    description,
+    control: locator,
+    equals: z.array(z.string().max(4000)).max(100),
+  }),
+  z.strictObject({
+    type: z.literal('text'),
+    description,
+    text: z.string().trim().min(1).max(2000),
+    fresh: z.boolean(),
+  }),
+  z.strictObject({
+    type: z.literal('url'),
+    description,
+    equals: z.string().min(1).max(4000),
+  }),
+  z.strictObject({ type: z.literal('absent'), description, control: locator }),
+]);
+
+/** A nonempty, bounded collection of outcome checks. */
+export const completionChecksSchema = z.array(completionCheckSchema).min(1).max(20);
+
+/** A validated observable outcome check. */
+export type CompletionCheck = z.infer<typeof completionCheckSchema>;
+
+
+/** The observed page information needed to evaluate outcome checks. */
+export interface VerificationState {
+  url: string;
+  text: string;
+  truncated: boolean;
+  controls: {
+    target: { id: string; version: number };
+    role: string;
+    label: string;
+    context: string;
+    groups?: { name: string }[] | undefined;
+    value?: string | undefined;
+    checked?: boolean | undefined;
+    selectedValues?: string[] | undefined;
+  }[];
+}
+
+type ObservedControl = VerificationState['controls'][number];
+type ControlLocator = z.infer<typeof controlLocatorSchema>;
+type ControlCheck = Extract<CompletionCheck, { control: ControlLocator }>;
+
+/** Match accessible characteristics independently of the observation's target ID. */
+function matchesControl(control: ObservedControl, locator: ControlLocator): boolean {
+  return (
+    control.role === locator.role &&
+    control.label === locator.label &&
+    (locator.context === null || control.context === locator.context) &&
+    (locator.group === null ||
+      control.groups?.some((group) => group.name === locator.group) === true)
+  );
+}
+
+/** Check visible text without treating a control's caption as an acknowledgement. */
+function matchesText(
+  check: Extract<CompletionCheck, { type: 'text' }>,
+  state: VerificationState,
+  baseline: VerificationState,
+): boolean {
+  const isVisible = state.text.includes(check.text);
+  const isControlLabel = state.controls.some((control) => control.label.includes(check.text));
+  const isFresh = !check.fresh || !baseline.text.includes(check.text);
+
+  return isVisible && !isControlLabel && isFresh;
+}
+
+/** Compare the observed control's state with the expected value. */
+function matchesControlValue(
+  check: Exclude<ControlCheck, { type: 'absent' }>,
+  control: ObservedControl,
+): boolean {
+  if (check.type === 'value') return control.value === check.equals;
+  if (check.type === 'checked') return control.checked === check.equals;
+
+  const selectedValues = control.selectedValues;
+  if (selectedValues === undefined) return false;
+
+  return (
+    selectedValues.length === check.equals.length &&
+    new Set(check.equals).size === check.equals.length &&
+    check.equals.every((value) => selectedValues.includes(value))
+  );
+}
+
+/** Resolve a control check against the current observation. */
+function matchesControlCheck(check: ControlCheck, state: VerificationState): boolean {
+  const semanticMatches = state.controls.filter((control) => matchesControl(control, check.control));
+
+  // A recycled target ID must not hide a control when checking for absence.
+  if (check.type === 'absent') return !state.truncated && semanticMatches.length === 0;
+
+  const matches = semanticMatches.filter(
+    (control) => check.control.id === null || control.target.id === check.control.id,
+  );
+
+  // A value can only be verified when the locator identifies exactly one control.
+  if (matches.length !== 1) return false;
+  return matchesControlValue(check, matches[0]!);
+}
+
+/** Deterministic checks of observable outcomes. This does not infer intent or prove backend persistence. */
+export function evaluateCompletionChecks(
+  checks: readonly CompletionCheck[],
+  state: VerificationState,
+  baseline: VerificationState = state,
+): { passed: boolean; checks: { description: string; passed: boolean }[] } {
+  const results = checks.map((check) => {
+    let passed: boolean;
+
+    if (check.type === 'text') {
+      passed = matchesText(check, state, baseline);
+    } else if (check.type === 'url') {
+      passed = state.url === check.equals;
+    } else {
+      passed = matchesControlCheck(check, state);
+    }
+
+    return { description: check.description, passed };
+  });
+
+  return {
+    passed: results.length > 0 && results.every((result) => result.passed),
+    checks: results,
+  };
+}
+
+/** A bounded, encoded screenshot with its capture metadata. */
+export const screenshotSchema = z
+  .strictObject({
+    data: z
+      .string()
+      .min(1)
+      .max(7_000_000)
+      .regex(/^[A-Za-z0-9+/]+={0,2}$/)
+      .refine((data) => data.length % 4 === 0),
+    mimeType: z.enum(['image/png', 'image/jpeg', 'image/webp']),
+    width: z.number().int().positive().max(8192),
+    height: z.number().int().positive().max(8192),
+    capturedAt: z.number().int().nonnegative(),
+    url: z.string().max(4000),
+  })
+  .superRefine((image, context) => {
+    try {
+      // Decode the payload before checking its size and file signature.
+      const bytes = globalThis.atob(image.data);
+
+      const signatureMatches =
+        image.mimeType === 'image/png'
+          ? bytes.startsWith('\x89PNG\r\n\x1a\n')
+          : image.mimeType === 'image/jpeg'
+            ? bytes.startsWith('\xff\xd8\xff')
+            : bytes.startsWith('RIFF') && bytes.slice(8, 12) === 'WEBP';
+
+      if (bytes.length > 5 * 1024 * 1024 || !signatureMatches) {
+        context.addIssue({
+          code: 'custom',
+          message: 'Screenshot bytes must match the image type and fit within 5 MiB.',
+        });
+      }
+    } catch {
+      context.addIssue({
+        code: 'custom',
+        message: 'Screenshot data must contain valid base64 image bytes.',
+      });
+    }
+  });

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.