@aiscene/shared 8.0.3 → 8.0.5

package/src/agent-tools/cli-report-session.ts

@@ -0,0 +1,130 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getMidsceneRunBaseDir, getMidsceneRunSubDir } from '../common';
+
+export interface CliReportSession {
+  version: 1;
+  sessionName: string;
+  targetIdentity?: string;
+  reportFileName: string;
+  reportPath: string;
+  createdAt: number;
+}
+
+const sessionDirName = 'cli-report-session';
+
+function sanitizeSessionName(sessionName: string): string {
+  return sessionName.replace(/[^a-zA-Z0-9._-]/g, '_') || 'default';
+}
+
+function sanitizeFileSegment(segment: string): string {
+  const sanitized = segment.replace(/[^a-zA-Z0-9._-]/g, '_') || 'unknown';
+  return sanitized.slice(0, 80);
+}
+
+function ensureHtmlFileName(reportFileName: string): string {
+  return reportFileName.endsWith('.html')
+    ? reportFileName
+    : `${reportFileName}.html`;
+}
+
+function formatDateForFileName(date: Date): string {
+  const pad = (value: number) => String(value).padStart(2, '0');
+  const day = [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+  ].join('-');
+  const time = [
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds()),
+  ].join('-');
+  return `${day}_${time}`;
+}
+
+function randomId(): string {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+function getCliReportSessionDir(): string {
+  const dir = join(getMidsceneRunBaseDir(), sessionDirName);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function getCliReportSessionPath(sessionName: string): string {
+  return join(
+    getCliReportSessionDir(),
+    `${sanitizeSessionName(sessionName)}.json`,
+  );
+}
+
+export function generateCliReportSession(
+  sessionName: string,
+  targetIdentity?: string,
+): CliReportSession {
+  const identitySegment = targetIdentity
+    ? `-${sanitizeFileSegment(targetIdentity)}`
+    : '';
+  const reportFileName = `${sanitizeSessionName(sessionName)}${identitySegment}-${formatDateForFileName(new Date())}-${randomId()}`;
+  const reportPath = join(
+    getMidsceneRunSubDir('report'),
+    ensureHtmlFileName(reportFileName),
+  );
+  const session: CliReportSession = {
+    version: 1,
+    sessionName,
+    ...(targetIdentity ? { targetIdentity } : {}),
+    reportFileName,
+    reportPath,
+    createdAt: Date.now(),
+  };
+  return session;
+}
+
+export function writeCliReportSession(session: CliReportSession): void {
+  writeFileSync(
+    getCliReportSessionPath(session.sessionName),
+    JSON.stringify(session, null, 2),
+    'utf-8',
+  );
+}
+
+export function createCliReportSession(
+  sessionName: string,
+  targetIdentity?: string,
+): CliReportSession {
+  const session = generateCliReportSession(sessionName, targetIdentity);
+  writeCliReportSession(session);
+  return session;
+}
+
+export function readCliReportSession(
+  sessionName: string,
+): CliReportSession | undefined {
+  const sessionPath = getCliReportSessionPath(sessionName);
+  if (!existsSync(sessionPath)) {
+    return undefined;
+  }
+
+  try {
+    const raw = readFileSync(sessionPath, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<CliReportSession>;
+    if (
+      parsed.version !== 1 ||
+      parsed.sessionName !== sessionName ||
+      typeof parsed.reportFileName !== 'string' ||
+      !parsed.reportFileName.trim() ||
+      /[\\/]/.test(parsed.reportFileName)
+    ) {
+      return undefined;
+    }
+
+    return parsed as CliReportSession;
+  } catch {
+    return undefined;
+  }
+}

package/src/agent-tools/error-formatter.ts

@@ -0,0 +1,177 @@
+/** A compact, transport-safe representation of an unknown thrown value. */
+export interface SerializedError {
+  name: string;
+  message: string;
+  stack?: string;
+  code?: string | number;
+  status?: string | number;
+  requestId?: string | number;
+}
+
+const maxSerializedStringLength = 4_096;
+const truncatedStringSuffix = '… [truncated]';
+
+interface SerializedErrorResult {
+  error: SerializedError;
+  hasMessage: boolean;
+}
+
+function isObject(error: unknown): error is object {
+  return (
+    (typeof error === 'object' && error !== null) || typeof error === 'function'
+  );
+}
+
+function safelyReadProperty(error: object, key: PropertyKey): unknown {
+  try {
+    return Reflect.get(error, key);
+  } catch {
+    return undefined;
+  }
+}
+
+function readBoundedDiagnostic(
+  error: object,
+  keys: readonly PropertyKey[],
+): string | number | undefined {
+  for (const key of keys) {
+    const value = safelyReadProperty(error, key);
+    if (typeof value === 'number') {
+      return value;
+    }
+    if (typeof value === 'string') {
+      return truncateSerializedErrorString(value);
+    }
+  }
+  return undefined;
+}
+
+/** Apply the same string bound used by {@link serializeError}. */
+export function truncateSerializedErrorString(value: string): string {
+  if (value.length <= maxSerializedStringLength) {
+    return value;
+  }
+
+  return `${value.slice(
+    0,
+    maxSerializedStringLength - truncatedStringSuffix.length,
+  )}${truncatedStringSuffix}`;
+}
+
+function readNonEmptyMessage(error: object): string | undefined {
+  const message = safelyReadProperty(error, 'message');
+  return typeof message === 'string' && message ? message : undefined;
+}
+
+function extractStringMessage(error: object): string | undefined {
+  const directMessage = readNonEmptyMessage(error);
+  if (directMessage) {
+    return directMessage;
+  }
+
+  for (const nestedKey of ['error', 'cause'] as const) {
+    const nestedError = safelyReadProperty(error, nestedKey);
+    if (!isObject(nestedError)) {
+      continue;
+    }
+
+    const nestedMessage = readNonEmptyMessage(nestedError);
+    if (nestedMessage) {
+      return nestedMessage;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ *
+ * Many SDK/transport layers reject with structured objects (e.g.
+ * `{ code, message }`, `{ error: { message } }`, `{ cause: { message } }`)
+ * rather than `Error` instances. This helper returns the bounded message from
+ * {@link serializeError}; message-less objects are summarized from the same
+ * diagnostic whitelist instead of serializing arbitrary payload fields.
+ */
+export function getErrorMessage(error: unknown): string {
+  const result = serializeErrorValue(error);
+  const serialized = result.error;
+  if (!isObject(error) || result.hasMessage) {
+    return serialized.message;
+  }
+
+  const summary: SerializedError = {
+    name: serialized.name,
+    message: serialized.message,
+  };
+  for (const key of ['code', 'status', 'requestId'] as const) {
+    const value = serialized[key];
+    if (value !== undefined) {
+      summary[key] = value;
+    }
+  }
+
+  return truncateSerializedErrorString(JSON.stringify(summary));
+}
+
+/** Safely read a stack trace from an unknown thrown value when one exists. */
+export function getErrorStack(error: unknown): string | undefined {
+  if (!isObject(error)) {
+    return undefined;
+  }
+
+  const stack = safelyReadProperty(error, 'stack');
+  return typeof stack === 'string' ? stack : undefined;
+}
+
+function serializeErrorValue(error: unknown): SerializedErrorResult {
+  if (!isObject(error)) {
+    const message = truncateSerializedErrorString(String(error));
+    return {
+      error: {
+        name: 'NonError',
+        message: message.trim() ? message : 'Empty string thrown',
+      },
+      hasMessage: Boolean(message.trim()),
+    };
+  }
+
+  const name = safelyReadProperty(error, 'name');
+  const serializedName = truncateSerializedErrorString(
+    typeof name === 'string' && name ? name : 'Error',
+  );
+  const message = extractStringMessage(error);
+  const serialized: SerializedError = {
+    name: serializedName,
+    message: truncateSerializedErrorString(
+      message ?? `${serializedName} without a message`,
+    ),
+  };
+
+  const stack = getErrorStack(error);
+  if (stack) {
+    serialized.stack = truncateSerializedErrorString(stack);
+  }
+
+  const code = readBoundedDiagnostic(error, ['code']);
+  const status = readBoundedDiagnostic(error, ['status', 'statusCode']);
+  const requestId = readBoundedDiagnostic(error, ['requestId', 'requestID']);
+  if (code !== undefined) serialized.code = code;
+  if (status !== undefined) serialized.status = status;
+  if (requestId !== undefined) serialized.requestId = requestId;
+
+  return {
+    error: serialized,
+    hasMessage: message !== undefined,
+  };
+}
+
+/**
+ * Extract a small, bounded diagnostic object suitable for JSON and test-runner
+ * transports. Only message, stack, and a few common diagnostic fields are
+ * retained. Arbitrary payloads are never visited, and nested errors are only
+ * inspected one level deep when the outer value has no message of its own.
+ */
+export function serializeError(error: unknown): SerializedError {
+  return serializeErrorValue(error).error;
+}

package/src/agent-tools/index.ts

@@ -0,0 +1,9 @@
+export * from './base-tools';
+export * from './tool-defaults';
+export * from './agent-behavior-init-args';
+export * from './init-arg-utils';
+export * from './error-formatter';
+export * from './tool-generator';
+export * from './types';
+export * from './chrome-path';
+export * from './observation-record';

package/src/agent-tools/init-arg-utils.ts

@@ -0,0 +1,105 @@
+import type { z } from 'zod';
+import { getKeyAliases, isRecord } from '../key-alias-utils';
+import type { ToolSchema } from './types';
+
+function readAliasedValue(
+  args: Record<string, unknown>,
+  key: string,
+): unknown | undefined {
+  for (const alias of getKeyAliases(key)) {
+    if (alias in args) {
+      return args[alias];
+    }
+  }
+
+  return undefined;
+}
+
+function readNamespacedArg(
+  args: Record<string, unknown>,
+  namespace: string,
+  key: string,
+): unknown | undefined {
+  // Lookup order: namespace object first, then flat dotted form, then bare key
+  // fallback. Namespace-aware inputs win so multi-platform callers cannot be
+  // cross-contaminated by a top-level bare `deviceId` leaking into the wrong
+  // platform.
+  const namespacedArgs = readAliasedValue(args, namespace);
+  if (isRecord(namespacedArgs)) {
+    const nestedValue = readAliasedValue(namespacedArgs, key);
+    if (nestedValue !== undefined) {
+      return nestedValue;
+    }
+  }
+
+  const dottedValue = readAliasedValue(args, `${namespace}.${key}`);
+  if (dottedValue !== undefined) {
+    return dottedValue;
+  }
+
+  const directValue = readAliasedValue(args, key);
+  if (directValue !== undefined) {
+    return directValue;
+  }
+
+  return undefined;
+}
+
+export function extractNamespacedArgs<
+  TFieldName extends string,
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+>(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly TFieldName[],
+): TArgs | undefined {
+  const extracted: Record<string, unknown> = {};
+
+  for (const key of keys) {
+    const value = readNamespacedArg(args, namespace, key);
+    if (value !== undefined) {
+      extracted[key] = value;
+    }
+  }
+
+  return Object.keys(extracted).length > 0 ? (extracted as TArgs) : undefined;
+}
+
+export function sanitizeNamespacedArgs(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly string[],
+): Record<string, unknown> {
+  const excludedKeys = new Set<string>(getKeyAliases(namespace));
+
+  for (const key of keys) {
+    for (const alias of getKeyAliases(key)) {
+      excludedKeys.add(alias);
+    }
+
+    for (const alias of getKeyAliases(`${namespace}.${key}`)) {
+      excludedKeys.add(alias);
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(args).filter(([key]) => !excludedKeys.has(key)),
+  );
+}
+
+/**
+ * Build a flat tool schema whose keys are dotted `"<namespace>.<field>"`.
+ *
+ * We intentionally stay flat (rather than `{ namespace: z.object({...}) }`) so
+ * that CLI (`--android.device-id`) and `--help` output share the same spelling.
+ * `readNamespacedArg` understands all three input shapes:
+ * nested namespace object, dotted flat key, and bare key fallback.
+ */
+export function createNamespacedInitArgSchema(
+  namespace: string,
+  shape: Record<string, z.ZodTypeAny>,
+): ToolSchema {
+  return Object.fromEntries(
+    Object.entries(shape).map(([key, value]) => [`${namespace}.${key}`, value]),
+  );
+}

package/src/agent-tools/observation-artifact.ts

@@ -0,0 +1,29 @@
+import type {
+  BaseAgent,
+  BaseUIObservation,
+  UIObservationRecord,
+} from './types';
+
+/** CLI-only bridge between an Agent runtime and observation artifacts. */
+export interface ObservationArtifactAdapter {
+  exportRecord(observation: BaseUIObservation): Promise<UIObservationRecord>;
+  loadRecord(record: UIObservationRecord): BaseUIObservation;
+}
+
+/** @internal Property key used by Core and the CLI artifact commands. */
+export const observationArtifactAdapterSymbol = Symbol(
+  'midscene.observationArtifactAdapter',
+);
+
+type ObservationArtifactAdapterHost = {
+  [observationArtifactAdapterSymbol]?: ObservationArtifactAdapter;
+};
+
+/** Read the CLI artifact capability attached by the Core Agent. */
+export function resolveObservationArtifactAdapter(
+  agent: BaseAgent,
+): ObservationArtifactAdapter | undefined {
+  return (agent as ObservationArtifactAdapterHost)[
+    observationArtifactAdapterSymbol
+  ];
+}