@ddwang/magnitude-core 0.3.1-ddwang.2 → 0.3.1-ddwang.3

package/dist/common/operation.js

@@ -1,23 +1,57 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
 import { OperationCancelledError, OperationDeadlineError } from '@/agent/errors';
+import logger from '@/logger';
+/** Preserve the original error and add only a payload-free snapshot, when extensible. */
+export function attachOperationDiagnostics(error, diagnostics) {
+    if (!(error instanceof Error))
+        return;
+    try {
+        if (!('operation' in error))
+            Object.defineProperty(error, 'operation', { value: diagnostics, enumerable: true });
+    }
+    catch { /* Caller-owned errors may be frozen or expose a custom property. */ }
+}
 // Keep context through async callbacks so a late callback cannot act on a reused agent.
 const operations = new AsyncLocalStorage();
 export class Operation {
     owner;
-    options;
+    kind;
+    onUpdate;
     controller = new AbortController();
     timer;
     closed = false;
     signal = this.controller.signal;
     deadline;
-    externalAbort = () => this.cancel(this.options.signal?.reason);
-    constructor(owner, options) {
+    externalSignal;
+    externalAbort = () => this.cancel(this.externalSignal?.reason);
+    id = randomUUID();
+    startedAt = Date.now();
+    started = performance.now();
+    finished;
+    cancelled;
+    idle;
+    announced = false;
+    outcome;
+    lastAction;
+    timings = {};
+    spans = new Set();
+    constructor(owner, options, kind = 'exec', onUpdate) {
         this.owner = owner;
-        this.options = options;
+        this.kind = kind;
+        this.onUpdate = onUpdate;
         if (options.deadline !== undefined && !Number.isFinite(options.deadline)) {
             throw new TypeError('deadline must be a finite Unix timestamp in milliseconds');
         }
         this.deadline = options.deadline;
+        this.externalSignal = options.signal;
+        this.signal.addEventListener('abort', () => {
+            this.cancelled = performance.now();
+            this.outcome = this.signal.reason instanceof OperationDeadlineError ? 'deadline' : 'cancelled';
+            attachOperationDiagnostics(this.signal.reason, this.snapshot());
+            this.publish();
+        }, { once: true });
         options.signal?.addEventListener('abort', this.externalAbort, { once: true });
         if (options.signal?.aborted)
             this.externalAbort();
@@ -33,31 +67,112 @@ export class Operation {
             this.timer = setTimeout(() => this.scheduleDeadline(), Math.min(remaining, 2_147_483_647));
     }
     cancel(reason) {
+        if (this.closed)
+            return;
         clearTimeout(this.timer);
         if (!this.signal.aborted)
             this.controller.abort(new OperationCancelledError(reason));
     }
     check() {
-        if (!this.signal.aborted && this.deadline !== undefined && Date.now() >= this.deadline) {
-            this.controller.abort(new OperationDeadlineError(this.deadline));
-        }
         if (this.signal.aborted)
             throw this.signal.reason;
         if (this.closed)
             throw new OperationCancelledError('Operation already finished');
+        if (this.deadline !== undefined && Date.now() >= this.deadline) {
+            this.controller.abort(new OperationDeadlineError(this.deadline));
+        }
+        if (this.signal.aborted)
+            throw this.signal.reason;
     }
     run(fn) {
         return operations.run(this, fn);
     }
+    announce() {
+        this.announced = true;
+        this.publish();
+    }
+    publish() {
+        if (!this.announced)
+            return;
+        try {
+            this.onUpdate?.(this.snapshot());
+        }
+        catch {
+            logger.warn('Operation diagnostic listener failed');
+        }
+    }
+    snapshot() {
+        const now = this.finished ?? performance.now();
+        const timings = {};
+        for (const [phase, timing] of Object.entries(this.timings))
+            timings[phase] = { ...timing };
+        let phase = 'preparing';
+        for (const span of this.spans) {
+            phase = span.phase;
+            const timing = timings[phase] ??= { count: 0, totalMs: 0 };
+            timing.count++;
+            timing.totalMs += now - span.started;
+        }
+        return {
+            id: this.id, kind: this.kind,
+            status: this.finished !== undefined ? 'finished' : this.cancelled !== undefined ? 'draining' : 'running',
+            outcome: this.outcome, phase, startedAt: this.startedAt, elapsedMs: now - this.started,
+            ...(this.cancelled !== undefined && this.finished !== undefined ? { cancellationToDrainMs: this.finished - this.cancelled } : {}),
+            ...(this.cancelled !== undefined && this.idle !== undefined ? { cancellationToIdleMs: this.idle - this.cancelled } : {}),
+            ...(this.lastAction ? { lastAction: { ...this.lastAction } } : {}), timings,
+        };
+    }
+    beginPhase(phase) {
+        if (this.closed)
+            return () => { };
+        const span = { phase, started: performance.now() };
+        this.spans.add(span);
+        this.publish();
+        return () => {
+            if (!this.spans.delete(span))
+                return;
+            const timing = this.timings[phase] ??= { count: 0, totalMs: 0 };
+            timing.count++;
+            timing.totalMs += performance.now() - span.started;
+            this.publish();
+        };
+    }
+    prepareAction(name) {
+        this.lastAction = { index: (this.lastAction?.index ?? 0) + 1, name, state: 'pending' };
+        this.publish();
+    }
+    actionState(state) {
+        if (this.lastAction)
+            this.lastAction.state = state;
+    }
+    fail(error) {
+        this.outcome ??= 'failed';
+        attachOperationDiagnostics(error, this.snapshot());
+    }
+    finish() {
+        this.finished = performance.now();
+        this.outcome ??= 'succeeded';
+        this.dispose();
+        this.publish();
+    }
+    markIdle() {
+        if (this.idle !== undefined)
+            return;
+        this.idle = performance.now();
+        this.publish();
+    }
     dispose() {
         this.closed = true;
         clearTimeout(this.timer);
-        this.options.signal?.removeEventListener('abort', this.externalAbort);
+        this.externalSignal?.removeEventListener('abort', this.externalAbort);
     }
 }
 export function currentOperation() {
     return operations.getStore();
 }
+export function withoutOperation(fn) {
+    return operations.exit(fn);
+}
 export function checkOperation() {
     currentOperation()?.check();
 }
@@ -66,6 +181,19 @@ export function operationOptions() {
     const operation = currentOperation();
     return { signal: operation?.signal, deadline: operation?.deadline };
 }
+export function beginOperationPhase(phase) {
+    return currentOperation()?.beginPhase(phase) ?? (() => { });
+}
+export async function measureOperation(phase, fn) {
+    const finish = beginOperationPhase(phase);
+    try {
+        checkOperation();
+        return await fn();
+    }
+    finally {
+        finish();
+    }
+}
 /** Wait for every branch, even when one fails, before releasing the operation. */
 export async function drainAll(promises) {
     const results = await Promise.allSettled(promises);

package/dist/common/operation.test.js

@@ -1,5 +1,5 @@
 import { expect, test } from 'bun:test';
-import { Operation, checkOperation, currentOperation, operationSleep } from './operation';
+import { Operation, checkOperation, currentOperation, measureOperation, operationSleep } from './operation';
 import { OperationCancelledError, OperationDeadlineError } from '@/agent/errors';
 test('operation context is isolated across concurrent owners and cleared outside them', async () => {
     const first = new Operation({}, {}), second = new Operation({}, {});
@@ -21,6 +21,8 @@ test('deadline wakes waits and remains a typed cause', async () => {
     try {
         await expect(operation.run(() => operationSleep(10_000))).rejects.toBeInstanceOf(OperationDeadlineError);
         expect(operation.signal.reason.deadline).toBe(deadline);
+        expect(operation.signal.reason.operation.outcome).toBe('deadline');
+        expect(operation.signal.reason.operation.status).toBe('draining');
     }
     finally {
         operation.dispose();
@@ -51,3 +53,37 @@ test('first abort wins and external listeners are removed on disposal', async ()
     expect(completed.signal.aborted).toBe(false);
     await expect(completed.run(async () => checkOperation())).rejects.toBeInstanceOf(OperationCancelledError);
 });
+test('phase timings handle nesting and concurrent spans without changing the active phase', async () => {
+    const operation = new Operation({}, {});
+    const outer = operation.beginPhase('action');
+    const first = operation.beginPhase('screenshot');
+    const second = operation.beginPhase('screenshot');
+    expect(operation.snapshot().phase).toBe('screenshot');
+    expect(operation.snapshot().timings.screenshot?.count).toBe(2);
+    first();
+    first(); // Closing a span twice is harmless.
+    expect(operation.snapshot().phase).toBe('screenshot');
+    second();
+    expect(operation.snapshot().phase).toBe('action');
+    await operation.run(async () => {
+        await expect(measureOperation('retry', async () => { throw new Error('fixture'); })).rejects.toThrow('fixture');
+    });
+    outer();
+    operation.finish();
+    const snapshot = operation.snapshot();
+    expect(snapshot.timings.action?.count).toBe(1);
+    expect(snapshot.timings.screenshot?.count).toBe(2);
+    expect(snapshot.timings.retry?.count).toBe(1);
+    expect(snapshot.timings.action.totalMs).toBeGreaterThanOrEqual(snapshot.timings.retry.totalMs);
+    operation.cancel();
+    expect(operation.snapshot()).toEqual(snapshot);
+});
+test('late callbacks cannot rewrite a completed outcome after its former deadline', async () => {
+    const operation = new Operation({}, { deadline: Date.now() + 10 });
+    operation.finish();
+    const completed = operation.snapshot();
+    await operationSleep(20);
+    expect(() => operation.check()).toThrow(OperationCancelledError);
+    expect(operation.snapshot()).toEqual(completed);
+    expect(operation.signal.aborted).toBe(false);
+});

package/dist/common/retry.js

@@ -1,4 +1,4 @@
-import { checkOperation, operationSleep } from './operation';
+import { checkOperation, measureOperation, operationSleep } from './operation';
 export async function retry(fn, options = {}) {
     const { retries = 3, delay = 0, maxDelay = Infinity, exponential = false, throwOnExhaustion = true, // Now defaults to true
     retryIf = () => true, onRetry } = options;
@@ -26,7 +26,7 @@ export async function retry(fn, options = {}) {
             }
             if (delay > 0) {
                 const currentDelay = Math.min(delay * Math.pow(multiplier, attempt), maxDelay);
-                await operationSleep(currentDelay);
+                await measureOperation('retry', () => operationSleep(currentDelay));
             }
         }
     }

package/dist/common/util.js

@@ -1,5 +1,5 @@
 import logger from "@/logger";
-import { checkOperation, operationSleep } from './operation';
+import { checkOperation, measureOperation, operationSleep } from './operation';
 export async function retryOnErrorIsSuccess(fnToRetry, retryOptions) {
     try {
         await retryOnError(fnToRetry, retryOptions);
@@ -52,7 +52,7 @@ export async function retryOnError(fnToRetry, retryOptions) {
             }
         }
         if (attempt < options.retryLimit)
-            await operationSleep(options.delayMs);
+            await measureOperation('retry', () => operationSleep(options.delayMs));
     }
     throw lastError;
     //if (options.throw) throw lastError;

package/dist/connectors/browserConnector.js

@@ -9,7 +9,7 @@ import { createHash } from 'node:crypto';
 import z from 'zod';
 import { BrowserBlockedError, BrowserRecovery, detectBlock, diagnosticUrl, retryAt } from '@/web/recovery';
 import { retry } from '@/common/retry';
-import { checkOperation, currentOperation, drainAll, operationSleep } from '@/common/operation';
+import { checkOperation, currentOperation, drainAll, measureOperation, operationSleep } from '@/common/operation';
 import { OperationCancelledError } from '@/agent/errors';
 // export type BrowserOptions = ({ instance: Browser } | { launchOptions?: LaunchOptions }) & {
 //     contextOptions?: BrowserContextOptions;
@@ -164,7 +164,7 @@ export class BrowserConnector {
         this.cancelWait = () => controller.abort(new OperationCancelledError('Browser stopped'));
         this.recovery.waitUntil = Date.now() + duration;
         try {
-            await operationSleep(duration, controller.signal);
+            await measureOperation('cooldown', () => operationSleep(duration, controller.signal));
         }
         finally {
             operation?.signal.removeEventListener('abort', abort);