@aiscene/shared 8.0.2 → 8.0.4

package/dist/es/cli/cli-error.mjs

@@ -0,0 +1,24 @@
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+class CLIError extends Error {
+    constructor(message, exitCode = 1){
+        super(message), _define_property(this, "exitCode", void 0), this.exitCode = exitCode;
+    }
+}
+function reportCLIError(error, log = console.error) {
+    if (error instanceof CLIError) {
+        log(error.message);
+        return error.exitCode;
+    }
+    log(error);
+    return 1;
+}
+export { CLIError, reportCLIError };

package/dist/es/cli/cli-runner.mjs

@@ -3,44 +3,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import dotenv from "dotenv";
 import { getDebug } from "../logger.mjs";
-function _define_property(obj, key, value) {
-    if (key in obj) Object.defineProperty(obj, key, {
-        value: value,
-        enumerable: true,
-        configurable: true,
-        writable: true
-    });
-    else obj[key] = value;
-    return obj;
-}
+import { formatCliValidationError, getCliOptionDisplay, parseCliArgs, parseValue } from "./cli-args.mjs";
+import { CLIError, reportCLIError } from "./cli-error.mjs";
 const debug = getDebug('cli-runner');
-class CLIError extends Error {
-    constructor(message, exitCode = 1){
-        super(message), _define_property(this, "exitCode", void 0), this.exitCode = exitCode;
-    }
-}
-function parseValue(raw) {
-    if (raw.startsWith('{') || raw.startsWith('[')) try {
-        return JSON.parse(raw);
-    } catch  {}
-    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
-    return raw;
-}
-function parseCliArgs(args) {
-    const result = {};
-    for(let i = 0; i < args.length; i++){
-        const arg = args[i];
-        if (!arg.startsWith('--')) continue;
-        const body = arg.slice(2);
-        const eqIdx = body.indexOf('=');
-        if (eqIdx >= 0) result[body.slice(0, eqIdx)] = parseValue(body.slice(eqIdx + 1));
-        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-            i++;
-            result[body] = parseValue(args[i]);
-        } else result[body] = true;
-    }
-    return result;
-}
 function outputContentItem(item, isError) {
     switch(item.type){
         case 'text':
@@ -72,10 +37,13 @@ function printCommandHelp(scriptName, cmd) {
     console.log(def.description);
     const schemaEntries = Object.entries(def.schema);
     if (schemaEntries.length > 0) {
+        const optionWidth = Math.max(22, ...schemaEntries.map(([key])=>getCliOptionDisplay(key, def.cli?.options?.[key]).label.length));
         console.log('\nOptions:');
         for (const [key, zodType] of schemaEntries){
+            const { label, aliases } = getCliOptionDisplay(key, def.cli?.options?.[key]);
             const desc = zodType.description ?? '';
-            console.log(`  --${key.padEnd(20)} ${desc}`);
+            const aliasText = aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : '';
+            console.log(`  ${label.padEnd(optionWidth)} ${desc}${aliasText}`);
         }
     }
 }
@@ -137,16 +105,18 @@ async function runToolsCLI(tools, scriptName, options) {
         throw new CLIError(`Unknown command: ${commandName}`);
     }
     const parsedArgs = parseCliArgs(restArgs);
-    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     if (true === parsedArgs.help) {
         debug('showing command help for: %s', match.name);
         printCommandHelp(scriptName, match);
         return;
     }
+    const cliValidationError = formatCliValidationError(scriptName, match.name, match.def, parsedArgs);
+    if (cliValidationError) throw new CLIError(cliValidationError);
+    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     const result = await match.def.handler(parsedArgs);
     debug('command %s completed, isError: %s', match.name, result.isError ?? false);
     outputResult(result);
     await tools.destroy();
     if (result.isError) throw new CLIError('Command failed', 1);
 }
-export { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI };
+export { CLIError, parseCliArgs, parseValue, removePrefix, reportCLIError, runToolsCLI };

package/dist/es/cli/index.mjs

@@ -1,2 +1,4 @@
-import { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI } from "./cli-runner.mjs";
-export { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI };
+import { CLIError, reportCLIError } from "./cli-error.mjs";
+import { parseCliArgs, parseValue } from "./cli-args.mjs";
+import { removePrefix, runToolsCLI } from "./cli-runner.mjs";
+export { CLIError, parseCliArgs, parseValue, removePrefix, reportCLIError, runToolsCLI };

package/dist/es/cli/interrupt.mjs

@@ -0,0 +1,116 @@
+const activeInterruptWaiters = new WeakMap();
+const noop = ()=>{};
+const sigintExitCode = 130;
+function guardTerminalCtrlC(input, onInterrupt) {
+    if (!input?.isTTY || !input.setRawMode) return noop;
+    const wasRaw = true === input.isRaw;
+    const wasFlowing = true === input.readableFlowing;
+    const onData = (chunk)=>{
+        const includesCtrlC = 'string' == typeof chunk && 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) {
+    const key = source;
+    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);
+    };
+}
+function hasActiveCliInterruptWaiter(source = process) {
+    return (activeInterruptWaiters.get(source) ?? 0) > 0;
+}
+function createCliInterruptWaiter(watchdogMs, options = {}) {
+    const source = options.source ?? process;
+    const input = options.input ?? (source === process ? process.stdin : void 0);
+    const forceExit = options.forceExit ?? (source === process ? (exitCode)=>{
+        process.exit(exitCode);
+    } : void 0);
+    const unregisterWaiter = registerCliInterruptWaiter(source);
+    let timer;
+    let finished = false;
+    let disposed = false;
+    let disposeInput = noop;
+    let resolveResult;
+    let rejectResult;
+    const result = new Promise((resolve, reject)=>{
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    const finish = (reason)=>{
+        if (finished) return;
+        finished = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = void 0;
+        }
+        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 = void 0;
+            }
+            unregisterWaiter();
+        }
+    }
+    const onTerminalCtrlC = ()=>{
+        if (!finished) return void finish('sigint');
+        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
+    };
+}
+function waitForCliInterrupt(watchdogMs, source = process, input = source === process ? process.stdin : void 0) {
+    const waiter = createCliInterruptWaiter(watchdogMs, {
+        source,
+        input
+    });
+    return waiter.result.finally(waiter.dispose);
+}
+export { createCliInterruptWaiter, hasActiveCliInterruptWaiter, waitForCliInterrupt };

package/dist/es/cli/record-command.mjs

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { getErrorMessage } from "../agent-tools/error-formatter.mjs";
+import { resolveObservationArtifactAdapter } from "../agent-tools/observation-artifact.mjs";
+import { writeUIObservationRecord } from "../agent-tools/observation-record.mjs";
+import { createCliInterruptWaiter } from "./interrupt.mjs";
+import { attachCliVerboseDumpListener, emitCliVerboseEvent } from "./verbose.mjs";
+const recordCliMetadata = {
+    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, extra) {
+    return {
+        positionals: base.positionals,
+        options: {
+            ...base.options ?? {},
+            ...extra?.options ?? {}
+        }
+    };
+}
+function createErrorResult(message) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message
+            }
+        ],
+        isError: true
+    };
+}
+function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata) {
+    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 = {})=>{
+            if ('start' !== args.action) 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;
+                let interruptWaiter;
+                try {
+                    const watchdogMs = args.watchdogMs ?? 300000;
+                    observer = await agent.startObserving({
+                        intervalMs: args.intervalMs,
+                        maxFrames: args.maxFrames,
+                        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);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Observation record saved: ${outputPath}`
+                            }
+                        ]
+                    };
+                } finally{
+                    try {
+                        await observer?.dispose?.();
+                    } finally{
+                        interruptWaiter?.dispose();
+                        unsubscribeVerbose();
+                    }
+                }
+            } catch (error) {
+                const errorMessage = getErrorMessage(error);
+                console.error('Error executing record:', errorMessage);
+                return createErrorResult(`Failed to execute record: ${errorMessage}`);
+            }
+        }
+    };
+}
+export { createRecordCliCommand };

package/dist/es/cli/screenshot-file.mjs

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

package/dist/es/cli/verbose-ai-act.mjs

@@ -0,0 +1,230 @@
+import { collectScreenshotRefs, pathForReportScreenshot } from "./verbose-screenshot.mjs";
+const cliAiActProgressScope = 'aiAct';
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+function compactText(value) {
+    if (null == value || '' === value) return '';
+    if ('string' == typeof value) return value.length > 180 ? `${value.slice(0, 177)}...` : value;
+    if ('number' == typeof value || 'boolean' == typeof value) return String(value);
+    try {
+        const json = JSON.stringify(value);
+        return json.length > 180 ? `${json.slice(0, 177)}...` : json;
+    } catch  {
+        return String(value);
+    }
+}
+function numericValue(value) {
+    return 'number' == typeof value && Number.isFinite(value) ? value : void 0;
+}
+function firstText(values) {
+    for (const value of values){
+        const text = compactText(value);
+        if (text) return text;
+    }
+    return '';
+}
+function planPrefix(event) {
+    const planIndex = numericValue(event.planIndex);
+    if (!planIndex) return '[Midscene][aiAct]';
+    const planLimit = numericValue(event.planLimit);
+    return `[Midscene][aiAct][Plan ${Math.round(planIndex)}${planLimit ? `/${Math.round(planLimit)}` : ''}]`;
+}
+function eventKey(event, suffix) {
+    const sequence = numericValue(event.sequence);
+    if (sequence) return `aiAct:${sequence}:${suffix}`;
+    return [
+        'aiAct',
+        compactText(event.phase),
+        compactText(event.planIndex),
+        suffix
+    ].filter(Boolean).join(':');
+}
+function integerText(value) {
+    return String(Math.round(value));
+}
+function numberTuple2(value) {
+    if (Array.isArray(value) && value.length >= 2 && 'number' == typeof value[0] && 'number' == typeof value[1]) return [
+        value[0],
+        value[1]
+    ];
+}
+function numberTuple4(value) {
+    if (Array.isArray(value) && value.length >= 4 && value.slice(0, 4).every((item)=>'number' == typeof item)) return [
+        value[0],
+        value[1],
+        value[2],
+        value[3]
+    ];
+}
+function parseAction(value) {
+    if (!isRecord(value) || 'string' != typeof value.name) return;
+    return {
+        name: value.name,
+        target: 'string' == typeof value.target ? value.target : void 0,
+        point: numberTuple2(value.point),
+        bbox: numberTuple4(value.bbox),
+        param: value.param
+    };
+}
+function formatPoint(point) {
+    return `(${integerText(point[0])}, ${integerText(point[1])})`;
+}
+function formatBbox(bbox) {
+    return `(${bbox.map(integerText).join(',')})`;
+}
+function sleepActionText(action) {
+    if ('Sleep' !== action.name || !isRecord(action.param)) return;
+    const timeMs = numericValue(action.param.timeMs) ?? numericValue(action.param.duration) ?? numericValue(action.param.timeoutMs);
+    return void 0 !== timeMs ? `Sleep ${integerText(timeMs)}ms` : void 0;
+}
+function plannedActionText(action) {
+    if (action.point) {
+        const targetSegment = action.target ? ` "${action.target}"` : '';
+        const bboxSegment = action.bbox ? `, bbox=${formatBbox(action.bbox)}` : '';
+        return `${action.name}${targetSegment} at ${formatPoint(action.point)}${bboxSegment}`;
+    }
+    const sleep = sleepActionText(action);
+    if (sleep) return sleep;
+    const paramText = compactText(action.param);
+    return paramText ? `${action.name}: ${paramText}` : action.name;
+}
+function runningActionText(action) {
+    if (action.point) return `${action.name} at ${formatPoint(action.point)}`;
+    return plannedActionText(action);
+}
+function normalizeAiActProgressEventForCli(event, screenshotOptions = {}) {
+    if (!isRecord(event) || event.scope !== cliAiActProgressScope) return;
+    const data = isRecord(event.data) ? event.data : {};
+    const screenshots = collectScreenshotRefs(data.screenshot, screenshotOptions);
+    const latestPath = screenshots.slice().reverse().find((item)=>'string' == typeof item.path && item.path.length > 0)?.path;
+    const screenshotPath = 'string' == typeof latestPath ? pathForReportScreenshot(latestPath, screenshotOptions.reportFile) : void 0;
+    const { prompt, planIndex, planLimit, action, thought, log, output, durationMs, error } = data;
+    return {
+        phase: event.phase,
+        sequence: event.sequence,
+        prompt,
+        planIndex,
+        planLimit,
+        action,
+        thought,
+        log,
+        output,
+        durationMs,
+        error,
+        ...screenshots.length > 0 ? {
+            screenshots
+        } : {},
+        ...screenshotPath ? {
+            screenshotPath
+        } : {}
+    };
+}
+function buildAiActProgressEventLines(event) {
+    const phase = 'string' == typeof event.phase ? event.phase : '';
+    const prefix = planPrefix(event);
+    const error = compactText(event.error);
+    const duration = 'number' == typeof event.durationMs ? ` cost=${Math.round(event.durationMs)}ms` : '';
+    const action = parseAction(event.action);
+    switch(phase){
+        case 'start':
+            {
+                const prompt = compactText(event.prompt);
+                return [
+                    {
+                        key: `aiAct:start:${prompt}`,
+                        text: prompt ? `[Midscene][aiAct] Start: ${prompt}` : '[Midscene][aiAct] Start'
+                    }
+                ];
+            }
+        case 'plan_thinking':
+            return event.screenshotPath ? [
+                {
+                    key: eventKey(event, 'thinking'),
+                    text: `${prefix} Thinking with the latest screenshot: ${event.screenshotPath}`
+                }
+            ] : [
+                {
+                    key: eventKey(event, 'thinking'),
+                    text: `${prefix} Thinking with the latest screenshot`
+                }
+            ];
+        case 'plan_planned':
+            {
+                const text = firstText([
+                    event.log,
+                    event.thought,
+                    event.output
+                ]);
+                return text ? [
+                    {
+                        key: eventKey(event, 'planned'),
+                        text: `${prefix} Planned: ${text}`
+                    }
+                ] : [];
+            }
+        case 'plan_action':
+            return action ? [
+                {
+                    key: eventKey(event, 'action'),
+                    text: `${prefix} Action: ${plannedActionText(action)}`
+                }
+            ] : [];
+        case 'plan_failed':
+            return [
+                {
+                    key: eventKey(event, 'plan_failed'),
+                    text: `${prefix} Failed${error ? `: ${error}` : ''}`
+                }
+            ];
+        case 'action_running':
+            return action ? [
+                {
+                    key: eventKey(event, 'action_running'),
+                    text: `[Midscene][aiAct][Action] Running: ${runningActionText(action)}`
+                }
+            ] : [];
+        case 'action_done':
+            return action ? [
+                {
+                    key: eventKey(event, 'action_done'),
+                    text: `[Midscene][aiAct][Action] Done: ${action.name}${duration}`
+                }
+            ] : [];
+        case 'action_failed':
+            return [
+                {
+                    key: eventKey(event, 'action_failed'),
+                    text: `[Midscene][aiAct][Action] Failed${action ? `: ${action.name}` : ''}${duration}${error ? ` error=${error}` : ''}`
+                }
+            ];
+        case 'complete':
+            {
+                const text = firstText([
+                    event.output,
+                    event.log,
+                    event.thought
+                ]);
+                return [
+                    {
+                        key: eventKey(event, 'complete'),
+                        text: `[Midscene][aiAct] Complete${text ? `: ${text}` : ''}`
+                    }
+                ];
+            }
+        case 'failed':
+            return [
+                {
+                    key: eventKey(event, 'failed'),
+                    text: `[Midscene][aiAct] Failed${error ? `: ${error}` : ''}`
+                }
+            ];
+        default:
+            return [];
+    }
+}
+const aiActCliProgressRenderer = {
+    normalize: normalizeAiActProgressEventForCli,
+    buildLines: buildAiActProgressEventLines
+};
+export { aiActCliProgressRenderer, buildAiActProgressEventLines, cliAiActProgressScope, normalizeAiActProgressEventForCli };