@aiscene/shared 8.0.2 → 8.0.4

package/src/cli/interrupt.ts

@@ -0,0 +1,207 @@
+export type CliInterruptReason = 'sigint' | 'sigterm' | 'sighup' | 'watchdog';
+
+type CliInterruptSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';
+
+export interface CliInterruptSource {
+  on(event: CliInterruptSignal, listener: () => void): unknown;
+  removeListener(event: CliInterruptSignal, listener: () => void): unknown;
+}
+
+export interface CliInterruptInputSource {
+  readonly isTTY?: boolean;
+  readonly isRaw?: boolean;
+  readonly readableFlowing?: boolean | null;
+  on(event: 'data', listener: (chunk: unknown) => void): unknown;
+  removeListener(event: 'data', listener: (chunk: unknown) => void): unknown;
+  setRawMode?(enabled: boolean): unknown;
+  pause?(): unknown;
+}
+
+export interface CliInterruptWaiter {
+  /** Resolves on the first stop signal or watchdog timeout. */
+  readonly result: Promise<CliInterruptReason>;
+  /** Release signal handlers after asynchronous finalization has completed. */
+  dispose(): void;
+}
+
+export interface CliInterruptWaiterOptions {
+  source?: CliInterruptSource;
+  input?: CliInterruptInputSource;
+  /** Called after restoring the terminal when Ctrl+C is pressed again. */
+  forceExit?: (exitCode: number) => void;
+}
+
+const activeInterruptWaiters = new WeakMap<object, number>();
+const noop = () => {};
+const sigintExitCode = 130;
+
+function guardTerminalCtrlC(
+  input: CliInterruptInputSource | undefined,
+  onInterrupt: () => void,
+): () => void {
+  if (!input?.isTTY || !input.setRawMode) return noop;
+
+  const wasRaw = input.isRaw === true;
+  const wasFlowing = input.readableFlowing === true;
+  const onData = (chunk: unknown) => {
+    const includesCtrlC =
+      (typeof chunk === 'string' && chunk.includes('\u0003')) ||
+      (chunk instanceof Uint8Array && chunk.includes(3));
+    if (includesCtrlC) onInterrupt();
+  };
+  const dispose = () => {
+    input.removeListener('data', onData);
+    try {
+      if (!wasFlowing) input.pause?.();
+    } finally {
+      if (!wasRaw) input.setRawMode?.(false);
+    }
+  };
+
+  input.setRawMode(true);
+  try {
+    input.on('data', onData);
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+  return dispose;
+}
+
+function registerCliInterruptWaiter(source: CliInterruptSource): () => void {
+  const key = source as object;
+  activeInterruptWaiters.set(key, (activeInterruptWaiters.get(key) ?? 0) + 1);
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+
+    const remaining = (activeInterruptWaiters.get(key) ?? 1) - 1;
+    if (remaining > 0) {
+      activeInterruptWaiters.set(key, remaining);
+    } else {
+      activeInterruptWaiters.delete(key);
+    }
+  };
+}
+
+/** Whether a foreground CLI command is currently waiting for this source. */
+export function hasActiveCliInterruptWaiter(
+  source: CliInterruptSource = process,
+): boolean {
+  return (activeInterruptWaiters.get(source as object) ?? 0) > 0;
+}
+
+/**
+ * Keep graceful-stop handlers installed until the caller has finished saving.
+ *
+ * Package runners such as pnpm can deliver SIGINT to the foreground child,
+ * immediately follow it with SIGTERM, then cause SIGHUP when the runner exits
+ * and its pseudo-terminal closes. Resolving on the first signal is not enough:
+ * removing any handler at that point lets a subsequent signal kill the child
+ * during asynchronous artifact finalization.
+ *
+ * On a TTY, Ctrl+C is captured as raw input so the package runner itself stays
+ * alive until the child has saved and restored the terminal. Signal handlers
+ * remain as the graceful-stop path for externally delivered termination.
+ */
+export function createCliInterruptWaiter(
+  watchdogMs: number,
+  options: CliInterruptWaiterOptions = {},
+): CliInterruptWaiter {
+  const source = options.source ?? process;
+  const input =
+    options.input ?? (source === process ? process.stdin : undefined);
+  const forceExit =
+    options.forceExit ??
+    (source === process
+      ? (exitCode: number) => {
+          process.exit(exitCode);
+        }
+      : undefined);
+  const unregisterWaiter = registerCliInterruptWaiter(source);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let finished = false;
+  let disposed = false;
+  let disposeInput = noop;
+  let resolveResult!: (reason: CliInterruptReason) => void;
+  let rejectResult!: (error: unknown) => void;
+
+  const result = new Promise<CliInterruptReason>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+
+  const finish = (reason: CliInterruptReason) => {
+    if (finished) return;
+    finished = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    resolveResult(reason);
+  };
+  const onSigint = () => finish('sigint');
+  const onSigterm = () => finish('sigterm');
+  const onSighup = () => finish('sighup');
+
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    source.removeListener('SIGINT', onSigint);
+    source.removeListener('SIGTERM', onSigterm);
+    source.removeListener('SIGHUP', onSighup);
+    try {
+      disposeInput();
+    } finally {
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      unregisterWaiter();
+    }
+  }
+
+  const onTerminalCtrlC = () => {
+    if (!finished) {
+      finish('sigint');
+      return;
+    }
+
+    // The first Ctrl+C protects asynchronous artifact finalization. A second
+    // explicit Ctrl+C is the user's escape hatch if device or file I/O hangs.
+    dispose();
+    forceExit?.(sigintExitCode);
+  };
+
+  try {
+    source.on('SIGINT', onSigint);
+    source.on('SIGTERM', onSigterm);
+    source.on('SIGHUP', onSighup);
+    disposeInput = guardTerminalCtrlC(input, onTerminalCtrlC);
+    if (watchdogMs > 0) {
+      timer = setTimeout(() => finish('watchdog'), watchdogMs);
+    }
+  } catch (error) {
+    dispose();
+    rejectResult(error);
+  }
+
+  return { result, dispose };
+}
+
+/**
+ * Wait for one stop request and release the handlers immediately afterwards.
+ * Long-running finalizers should use {@link createCliInterruptWaiter} instead.
+ */
+export function waitForCliInterrupt(
+  watchdogMs: number,
+  source: CliInterruptSource = process,
+  input: CliInterruptInputSource | undefined = source === process
+    ? process.stdin
+    : undefined,
+): Promise<CliInterruptReason> {
+  const waiter = createCliInterruptWaiter(watchdogMs, { source, input });
+  return waiter.result.finally(waiter.dispose);
+}

package/src/cli/record-command.ts

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { getErrorMessage } from '../agent-tools/error-formatter';
+import { resolveObservationArtifactAdapter } from '../agent-tools/observation-artifact';
+import { writeUIObservationRecord } from '../agent-tools/observation-record';
+import type {
+  BaseAgent,
+  ToolCliMetadata,
+  ToolDefinition,
+  ToolResult,
+  ToolSchema,
+} from '../agent-tools/types';
+import { type CliInterruptWaiter, createCliInterruptWaiter } from './interrupt';
+import { attachCliVerboseDumpListener, emitCliVerboseEvent } from './verbose';
+
+const recordCliMetadata: ToolCliMetadata = {
+  positionals: ['action'],
+  options: {
+    intervalMs: {
+      preferredName: 'interval-ms',
+      aliases: ['intervalMs'],
+    },
+    maxFrames: {
+      preferredName: 'max-frames',
+      aliases: ['maxFrames'],
+    },
+    watchdogMs: {
+      preferredName: 'watchdog-ms',
+      aliases: ['watchdogMs'],
+    },
+    action: {
+      hidden: true,
+    },
+  },
+};
+
+function mergeCliMetadata(
+  base: ToolCliMetadata,
+  extra?: ToolCliMetadata,
+): ToolCliMetadata {
+  return {
+    positionals: base.positionals,
+    options: {
+      ...(base.options ?? {}),
+      ...(extra?.options ?? {}),
+    },
+  };
+}
+
+function createErrorResult(message: string): ToolResult {
+  return {
+    content: [{ type: 'text', text: message }],
+    isError: true,
+  };
+}
+
+/** Create the foreground recording command exposed only by Midscene CLIs. */
+export function createRecordCliCommand(
+  getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>,
+  initArgSchema: ToolSchema = {},
+  initArgCliMetadata?: ToolCliMetadata,
+): ToolDefinition {
+  return {
+    name: 'record',
+    description:
+      'Record the page/screen in the foreground until Ctrl+C or a termination signal, then save the ordered frame window for a later assert command.',
+    schema: {
+      action: z
+        .literal('start')
+        .describe('Start a foreground recording. Press Ctrl+C to finish.'),
+      output: z
+        .string()
+        .optional()
+        .describe(
+          'Path for the JSON observation manifest. Frames are stored in an adjacent <name>.frames directory. Defaults to a generated path under midscene_run/output.',
+        ),
+      intervalMs: z
+        .number()
+        .min(200)
+        .optional()
+        .describe(
+          'Sampling interval in milliseconds. Defaults to 1000; minimum 200 (5fps).',
+        ),
+      maxFrames: z
+        .number()
+        .int()
+        .min(2)
+        .optional()
+        .describe('Maximum buffered frames. Defaults to 30; minimum 2.'),
+      watchdogMs: z
+        .number()
+        .min(0)
+        .optional()
+        .describe(
+          'Safety timeout in milliseconds. Defaults to 300000 (5 minutes); 0 disables it.',
+        ),
+      ...initArgSchema,
+    },
+    cli: mergeCliMetadata(recordCliMetadata, initArgCliMetadata),
+    handler: async (
+      args: Record<string, unknown> = {},
+    ): Promise<ToolResult> => {
+      if (args.action !== 'start') {
+        return createErrorResult(
+          'record requires the start operation (for example: record start --output ./observation.json)',
+        );
+      }
+
+      try {
+        const agent = await getAgent(args);
+        emitCliVerboseEvent({ event: 'agent_ready', tool: 'record' });
+        if (!agent.startObserving) {
+          throw new Error(
+            'record is not supported because this agent does not provide startObserving',
+          );
+        }
+        const observationArtifacts = resolveObservationArtifactAdapter(agent);
+        if (!observationArtifacts) {
+          throw new Error(
+            'record is not supported because this agent does not provide observation artifact persistence',
+          );
+        }
+        const unsubscribeVerbose = attachCliVerboseDumpListener(agent, {
+          toolName: 'record',
+        });
+        let observer:
+          | Awaited<ReturnType<NonNullable<BaseAgent['startObserving']>>>
+          | undefined;
+        let interruptWaiter: CliInterruptWaiter | undefined;
+        try {
+          const watchdogMs = (args.watchdogMs as number | undefined) ?? 300_000;
+          observer = await agent.startObserving({
+            intervalMs: args.intervalMs as number | undefined,
+            maxFrames: args.maxFrames as number | undefined,
+            watchdogMs,
+          });
+          interruptWaiter = createCliInterruptWaiter(watchdogMs);
+          emitCliVerboseEvent({
+            event: 'recording_ready',
+            tool: 'record',
+            watchdogMs,
+          });
+          const stopReason = await interruptWaiter.result;
+          emitCliVerboseEvent({
+            event: 'recording_stopping',
+            tool: 'record',
+            reason: stopReason,
+          });
+          const observation = await observer.stop();
+          const record = await observationArtifacts.exportRecord(observation);
+          const outputPath = writeUIObservationRecord(
+            record,
+            args.output as string | undefined,
+          );
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Observation record saved: ${outputPath}`,
+              },
+            ],
+          };
+        } finally {
+          try {
+            await observer?.dispose?.();
+          } finally {
+            interruptWaiter?.dispose();
+            unsubscribeVerbose();
+          }
+        }
+      } catch (error: unknown) {
+        const errorMessage = getErrorMessage(error);
+        console.error('Error executing record:', errorMessage);
+        return createErrorResult(`Failed to execute record: ${errorMessage}`);
+      }
+    },
+  };
+}

package/src/cli/screenshot-file.ts

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export interface WriteCliScreenshotFileOptions {
+  id?: unknown;
+  mimeType?: unknown;
+  extension?: unknown;
+  directoryPath?: string;
+  directoryName?: string;
+  filenamePrefix?: string;
+  overwrite?: boolean;
+}
+
+function safeScreenshotFilenamePart(value: unknown): string {
+  const text = typeof value === 'string' && value.length > 0 ? value : 'shot';
+  return text.replace(/[^a-zA-Z0-9._-]/g, '_') || 'shot';
+}
+
+function extensionFromImageMetadata(
+  mimeType: unknown,
+  extension: unknown,
+): 'png' | 'jpeg' {
+  if (extension === 'jpeg' || extension === 'jpg') {
+    return 'jpeg';
+  }
+  if (extension === 'png') {
+    return 'png';
+  }
+  return mimeType === 'image/jpeg' ? 'jpeg' : 'png';
+}
+
+export function writeCliScreenshotFile(
+  rawBase64: string,
+  options: WriteCliScreenshotFileOptions = {},
+): string {
+  const extension = extensionFromImageMetadata(
+    options.mimeType,
+    options.extension,
+  );
+  const directory = options.directoryPath
+    ? options.directoryPath
+    : options.directoryName
+      ? join(tmpdir(), options.directoryName)
+      : tmpdir();
+  if (!existsSync(directory)) {
+    mkdirSync(directory, { recursive: true });
+  }
+
+  const filename =
+    options.id !== undefined
+      ? `${safeScreenshotFilenamePart(options.id)}.${extension}`
+      : `${options.filenamePrefix ?? 'screenshot'}-${Date.now()}.${extension}`;
+  const filePath = join(directory, filename);
+
+  if (options.overwrite !== false || !existsSync(filePath)) {
+    writeFileSync(filePath, Buffer.from(rawBase64, 'base64'));
+  }
+
+  return filePath;
+}