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

package/dist/agent/browserAgent.js

@@ -6,6 +6,7 @@ import { partitionHtml, serializeToMarkdown } from 'magnitude-extract';
 import EventEmitter from "eventemitter3";
 import { retry } from "@/common/retry";
 import { checkOperation } from '@/common/operation';
+import { getVisiblePageContent } from '@/web/pageContent';
 // export interface StartAgentWithWebOptions {
 //     agentBaseOptions?: Partial<AgentOptions>;
 //     webConnectorOptions?: BrowserConnectorOptions;
@@ -29,47 +30,6 @@ export async function startBrowserAgent(options //StartAgentWithWebOptions = {}
     //console.log('agent started');
     return agent;
 }
-async function getFullPageContent(page) {
-    checkOperation();
-    // 1. Get all iframe element handles
-    const iframeHandles = await page.locator('iframe').elementHandles();
-    // 2. Iterate through each iframe handle
-    for (const iframeHandle of iframeHandles) {
-        checkOperation();
-        // 3. Get the Frame object for the iframe
-        const frame = await iframeHandle.contentFrame();
-        checkOperation();
-        if (frame) {
-            // 4. Get the HTML content of the iframe
-            const iframeContent = await frame.content();
-            checkOperation();
-            // 5. Use evaluate to replace the iframe element with its content.
-            // We pass the content as an argument to avoid issues with string escaping.
-            await iframeHandle.evaluate((iframeNode, { content }) => {
-                // Create a new div element to hold the iframe's content
-                const div = document.createElement('div');
-                // Use DOMParser to handle Trusted Types restrictions
-                const parser = new DOMParser();
-                const doc = parser.parseFromString(content, 'text/html');
-                // Move all body children to the div
-                while (doc.body.firstChild) {
-                    div.appendChild(doc.body.firstChild);
-                }
-                // Also preserve any head elements that might be important (styles, etc)
-                const headElements = doc.head.querySelectorAll('style, link[rel="stylesheet"]');
-                headElements.forEach(el => div.appendChild(el.cloneNode(true)));
-                // Add a data-attribute to mark that this was an expanded iframe
-                div.dataset.expandedFromIframe = 'true';
-                div.dataset.iframeSrc = iframeNode.getAttribute('src') || '';
-                // Replace the iframeNode with the new div
-                iframeNode.parentNode?.replaceChild(div, iframeNode);
-            }, { content: iframeContent });
-        }
-    }
-    // 6. Return the final, modified page content
-    checkOperation();
-    return page.content();
-}
 export class BrowserAgent extends Agent {
     browserAgentEvents = new EventEmitter();
     constructor({ agentOptions, browserOptions }) {
@@ -91,15 +51,14 @@ export class BrowserAgent extends Agent {
             this.browserAgentEvents.emit('nav', url);
             checkOperation();
             await this.require(BrowserConnector).getHarness().navigate(url);
-        });
+        }, 'nav');
     }
     async extract(instructions, schema, options = {}) {
-        return this.runOperation(options, () => this._extract(instructions, schema));
+        return this.runOperation(options, () => this._extract(instructions, schema), 'extract');
     }
     async _extract(instructions, schema) {
         this.browserAgentEvents.emit('extractStarted', instructions, schema);
-        //const htmlContent = await this.page.content();
-        const htmlContent = await retry(async () => await getFullPageContent(this.page), { retries: 5, delay: 200, exponential: true });
+        const htmlContent = await retry(() => getVisiblePageContent(this.page), { retries: 5, delay: 200, exponential: true });
         // const accessibilityTree = await this.page.accessibility.snapshot({ interestingOnly: true });
         // const pageRepr = renderMinimalAccessibilityTree(accessibilityTree);
         const partitionOptions = {

package/dist/agent/errors.d.ts

@@ -1,8 +1,10 @@
+import type { OperationDiagnostics } from '@/common/operation';
 export interface AgentErrorOptions {
     variant?: string;
     adaptable?: boolean;
 }
 export declare class AgentError extends Error {
+    readonly operation?: OperationDiagnostics;
     readonly options: Required<AgentErrorOptions>;
     constructor(message: string, options?: AgentErrorOptions);
 }

package/dist/agent/errors.js

@@ -51,7 +51,7 @@ export class OperationDeadlineError extends AgentError {
 }
 export class AgentBusyError extends AgentError {
     constructor() {
-        super('Agent has an active operation; await whenIdle() before reusing it', { variant: 'busy' });
+        super('Agent has pending work; await whenIdle() before reusing it', { variant: 'busy' });
         this.name = 'AgentBusyError';
     }
 }

package/dist/agent/index.d.ts

@@ -5,7 +5,7 @@ import { AgentEvents } from "@/common/events";
 import { AgentConnector } from '@/connectors';
 import { RenderableContent } from '@/memory/observation';
 import { LLMClient } from "@/ai/types";
-import { type OperationOptions } from '@/common/operation';
+import { type OperationDiagnostics, type OperationKind, type OperationOptions } from '@/common/operation';
 import { AgentMemory, MemoryRenderOptions } from "@/memory";
 import { ActionDefinition } from "@/actions";
 import { MultiModelHarness } from '@/ai/multiModelHarness';
@@ -33,18 +33,30 @@ export declare class Agent {
     private _paused;
     private _pauseResolve;
     private activeOperation?;
+    private latestOperation?;
     private idle;
-    private stopped;
+    private resolveIdle?;
+    private pendingWork;
+    private lifecycleTail;
+    private lifecycleRequest?;
+    private lifecycleState;
+    private telemetryStarted;
     protected latestTaskMemory: AgentMemory;
     constructor(baseConfig?: Partial<AgentOptions>);
     getConnector<C extends AgentConnector>(connectorClass: new (...args: any[]) => C): C | undefined;
     require<C extends AgentConnector>(connectorClass: new (...args: any[]) => C): C;
     start(): Promise<void>;
+    get lifecycle(): 'new' | 'starting' | 'ready' | 'stopping' | 'stopped';
+    private beginWork;
+    private endWork;
+    private scheduleLifecycle;
     identifyAction(action: Action): ActionDefinition<any>;
     /** True until underlying work settles, including after a cancelled caller returns. */
     get busy(): boolean;
     whenIdle(): Promise<void>;
-    protected runOperation<T>(options: OperationOptions, fn: () => Promise<T>): Promise<T>;
+    /** A payload-free snapshot of the active or most recent operation. */
+    get operation(): OperationDiagnostics | undefined;
+    protected runOperation<T>(options: OperationOptions, fn: () => Promise<T>, kind?: OperationKind): Promise<T>;
     exec(action: Action, memory?: AgentMemory, options?: OperationOptions): Promise<unknown>;
     private _exec;
     protected _recordConnectorObservations(memory: AgentMemory): Promise<void>;
@@ -61,4 +73,5 @@ export declare class Agent {
     resume(): void;
     get paused(): boolean;
     stop(): Promise<void>;
+    private stopConnectors;
 }

package/dist/agent/index.js

@@ -3,7 +3,7 @@ import EventEmitter from "eventemitter3";
 import z from "zod";
 import { Observation } from '@/memory/observation';
 import { ActionLimitError, AgentBusyError, AgentError } from "@/agent/errors";
-import { Operation, checkOperation, currentOperation, operationOptions, untilAborted } from '@/common/operation';
+import { Operation, attachOperationDiagnostics, checkOperation, currentOperation, measureOperation, operationOptions, untilAborted, withoutOperation, } from '@/common/operation';
 import { AgentMemory } from "@/memory";
 import { taskActions } from "@/actions/taskActions";
 import { memoryActions } from '@/actions/memoryActions';
@@ -46,8 +46,14 @@ export class Agent {
     _paused = false;
     _pauseResolve = null;
     activeOperation;
+    latestOperation;
     idle = Promise.resolve();
-    stopped = false;
+    resolveIdle;
+    pendingWork = 0;
+    lifecycleTail = Promise.resolve();
+    lifecycleRequest;
+    lifecycleState = 'new';
+    telemetryStarted = false;
     latestTaskMemory; // | null = null;
     constructor(baseConfig = {}) {
         this.options = {
@@ -114,27 +120,63 @@ export class Agent {
         return connector;
     }
     async start() {
+        return this.scheduleLifecycle('start', async () => {
+            if (this.lifecycleState === 'ready')
+                return;
+            this.lifecycleState = 'starting';
+            if (this.options.telemetry && !this.telemetryStarted) {
+                telemetrifyAgent(this);
+                this.telemetryStarted = true;
+            }
+            try {
+                await this.models.setup();
+                for (const connector of this.connectors)
+                    await connector.onStart?.();
+            }
+            catch (error) {
+                await this.stopConnectors();
+                this.lifecycleState = 'stopped';
+                throw error;
+            }
+            this.lifecycleState = 'ready';
+            this.events.emit('start');
+        });
+    }
+    get lifecycle() {
+        return this.lifecycleState;
+    }
+    beginWork() {
+        if (this.pendingWork++ === 0)
+            this.idle = new Promise(resolve => { this.resolveIdle = resolve; });
+    }
+    endWork() {
+        if (--this.pendingWork === 0) {
+            const resolve = this.resolveIdle;
+            this.resolveIdle = undefined;
+            withoutOperation(() => this.latestOperation?.markIdle());
+            resolve?.();
+        }
+    }
+    scheduleLifecycle(kind, fn) {
         checkOperation();
-        if (this.busy)
+        if (kind === 'start' && this.activeOperation)
             throw new AgentBusyError();
-        // Register telemetry if enabled - do on start instead of cons to prevent weird subclass event issues
-        if (this.options.telemetry)
-            telemetrifyAgent(this);
-        //console.log('setting up model')
-        await this.models.setup();
-        //console.log('done setting up model')
-        logger.info("Agent: Starting connectors...");
-        for (const connector of this.connectors) {
-            if (connector.onStart)
-                await connector.onStart();
-        }
-        this.events.emit('start');
-        this.stopped = false;
-        logger.info("Agent: All connectors started.");
-        // logger.info("Making initial observations...");
-        // await this._recordConnectorObservations();
-        // logger.info("Initial observations recorded");
-        // Initial observations are handled by the first getObservations call in exec
+        if (this.lifecycleRequest?.kind === kind)
+            return this.lifecycleRequest.promise;
+        this.beginWork();
+        // Cleanup belongs to the agent, not the operation that requested stop().
+        return withoutOperation(() => {
+            const promise = this.lifecycleTail.then(fn).finally(() => {
+                if (this.lifecycleRequest?.promise === promise)
+                    this.lifecycleRequest = undefined;
+                this.endWork();
+            });
+            this.lifecycleRequest = { kind, promise };
+            this.lifecycleTail = promise.catch(() => { });
+            if (kind === 'stop')
+                this.activeOperation?.cancel('Agent stopped');
+            return promise;
+        });
     }
     identifyAction(action) {
         // Get definition corresponding to an action
@@ -148,23 +190,34 @@ export class Agent {
     }
     /** True until underlying work settles, including after a cancelled caller returns. */
     get busy() {
-        return this.activeOperation !== undefined;
+        return this.pendingWork > 0;
     }
     whenIdle() {
         return this.idle;
     }
-    async runOperation(options, fn) {
+    /** A payload-free snapshot of the active or most recent operation. */
+    get operation() {
+        return this.latestOperation?.snapshot();
+    }
+    async runOperation(options, fn, kind = 'exec') {
         const inherited = currentOperation();
         if (inherited?.owner === this)
             inherited.check();
-        if (this.busy)
-            throw new AgentBusyError();
-        if (this.stopped)
+        if (this.busy) {
+            const error = new AgentBusyError();
+            if (this.activeOperation)
+                attachOperationDiagnostics(error, this.activeOperation.snapshot());
+            throw error;
+        }
+        if (this.lifecycleState === 'stopped')
             throw new AgentError('Agent is stopped; call start() before using it');
-        const operation = new Operation(this, options);
+        const operation = new Operation(this, options, kind, snapshot => {
+            this.events.emit('operation', snapshot);
+        });
         this.activeOperation = operation;
-        let markIdle;
-        this.idle = new Promise(resolve => { markIdle = resolve; });
+        this.latestOperation = operation;
+        this.beginWork();
+        operation.announce();
         const worker = operation.run(async () => {
             operation.check();
             try {
@@ -174,10 +227,13 @@ export class Agent {
                 operation.check(); // Preserve the cancellation/deadline cause through downstream errors.
             }
         });
-        const settled = worker.finally(() => {
-            operation.dispose();
+        const settled = worker.catch(error => {
+            operation.fail(error);
+            throw error;
+        }).finally(() => {
+            operation.finish();
             this.activeOperation = undefined;
-            markIdle();
+            this.endWork();
         });
         return untilAborted(settled, operation.signal);
     }
@@ -203,6 +259,9 @@ export class Agent {
         if (!parsed.success) {
             throw new AgentError(`Generated action '${action.variant}' violates input schema: ${parsed.error.message}`, { adaptable: true });
         }
+        const operation = currentOperation();
+        operation?.prepareAction(actionDefinition.name);
+        checkOperation();
         const memoryOnly = memoryActions.includes(actionDefinition);
         if (!memoryOnly)
             for (const connector of this.connectors) {
@@ -211,7 +270,19 @@ export class Agent {
             }
         this.events.emit('actionStarted', action);
         checkOperation();
-        const data = await actionDefinition.resolver({ input: parsed.data, agent: this, memory, ...operationOptions() });
+        const data = await measureOperation('action', async () => {
+            const options = operationOptions();
+            operation?.actionState('started');
+            try {
+                const result = await actionDefinition.resolver({ input: parsed.data, agent: this, memory, ...options });
+                operation?.actionState('completed');
+                return result;
+            }
+            catch (error) {
+                operation?.actionState('failed');
+                throw error;
+            }
+        });
         checkOperation();
         this.events.emit('actionDone', action);
         checkOperation();
@@ -231,24 +302,23 @@ export class Agent {
         return data;
     }
     async _recordConnectorObservations(memory) {
-        checkOperation();
-        for (const connector of this.connectors) {
-            // could do Promise.all if matters
-            const connObservations = connector.collectObservations ? await connector.collectObservations(operationOptions()) : [];
-            checkOperation();
-            //observations.push(...connObservations);
-            for (const obs of connObservations) {
-                memory.recordObservation(obs);
+        return measureOperation('observations', async () => {
+            for (const connector of this.connectors) {
+                const connObservations = connector.collectObservations ? await connector.collectObservations(operationOptions()) : [];
+                checkOperation();
+                for (const obs of connObservations) {
+                    memory.recordObservation(obs);
+                }
             }
-        }
-        this.events.emit('observationsRecorded');
+            this.events.emit('observationsRecorded');
+        });
     }
     get memory() {
         //if (!this.latestTaskMemory) throw new Error("No memory available");
         return this.latestTaskMemory;
     }
     async act(taskOrSteps, options = {}) {
-        return this.runOperation(options, () => this._runAct(taskOrSteps, options));
+        return this.runOperation(options, () => this._runAct(taskOrSteps, options), 'act');
     }
     async _runAct(taskOrSteps, options) {
         const instructions = [
@@ -286,28 +356,25 @@ export class Agent {
         })(task));
     }
     async _buildContext(memory, options) {
-        checkOperation();
-        const messages = await memory.render(options);
-        checkOperation();
-        const connectorInstructions = [];
-        for (const connector of this.connectors) {
-            if (connector.getInstructions) {
-                const instructions = await connector.getInstructions(operationOptions());
-                checkOperation();
-                if (instructions) {
-                    connectorInstructions.push({
-                        connectorId: connector.id,
-                        instructions: instructions
-                    });
+        return measureOperation('context', async () => {
+            const messages = await memory.render(options);
+            checkOperation();
+            const connectorInstructions = [];
+            for (const connector of this.connectors) {
+                if (connector.getInstructions) {
+                    const instructions = await connector.getInstructions(operationOptions());
+                    checkOperation();
+                    if (instructions) {
+                        connectorInstructions.push({ connectorId: connector.id, instructions });
+                    }
                 }
             }
-        }
-        return {
-            instructions: memory.instructions,
-            observationContent: messages,
-            //observationContent: content,
-            connectorInstructions: connectorInstructions
-        };
+            return {
+                instructions: memory.instructions,
+                observationContent: messages,
+                connectorInstructions,
+            };
+        });
     }
     async _act(description, memory, options = {}) {
         checkOperation();
@@ -433,7 +500,7 @@ export class Agent {
             await this._recordConnectorObservations(this.latestTaskMemory);
             const memoryContext = await this._buildContext(this.memory, options);
             return await this.models.query(memoryContext, query, schema);
-        });
+        }, 'query');
     }
     async queueDone() {
         checkOperation();
@@ -449,9 +516,13 @@ export class Agent {
             return; // A pause listener may have resumed synchronously.
         logger.info("Agent: Paused");
         try {
-            await untilAborted(new Promise((resolve) => {
-                this._pauseResolve = resolve;
-            }), currentOperation()?.signal);
+            await measureOperation('paused', async () => {
+                if (!this._paused)
+                    return; // A diagnostic listener may have resumed.
+                await untilAborted(new Promise((resolve) => {
+                    this._pauseResolve = resolve;
+                }), currentOperation()?.signal);
+            });
         }
         finally {
             this._pauseResolve = null;
@@ -475,19 +546,20 @@ export class Agent {
         return this._paused;
     }
     async stop() {
-        checkOperation();
-        /**
-         * Stop the agent and close the browser context.
-         * May be called asynchronously and interrupt an agent in the middle of a action sequence.
-         */
-        this.stopped = true;
-        this.activeOperation?.cancel('Agent stopped');
-        this.doneActing = true;
-        if (this._paused) {
+        return this.scheduleLifecycle('stop', async () => {
+            if (this.lifecycleState === 'stopped')
+                return;
+            this.lifecycleState = 'stopping';
+            this.doneActing = true;
             this._paused = false;
             this._pauseResolve?.();
             this._pauseResolve = null;
-        }
+            await this.stopConnectors();
+            this.lifecycleState = 'stopped';
+            this.events.emit('stop');
+        });
+    }
+    async stopConnectors() {
         logger.info("Agent: Stopping connectors...");
         for (const connector of this.connectors) {
             try {
@@ -498,7 +570,6 @@ export class Agent {
                 logger.warn(`Agent: Error stopping connector ${connector.id}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        this.events.emit('stop');
         logger.info("Agent: All connectors stopped.");
         logger.info("Agent: Stopped successfully.");
     }

package/dist/ai/modelHarness.js

@@ -11,7 +11,7 @@ import { parsePlannerResponse, PlannerResponseError, memoryUpdatesSchema } from
 import { anthropicOutputFormat, plannerSchema, usesStructuredOutput } from './structuredOutput';
 import { ModelResponseError } from './modelResponseError';
 import { DEFAULT_BASETEN_MODEL } from './baseten';
-import { checkOperation, operationOptions } from '@/common/operation';
+import { beginOperationPhase, checkOperation, operationOptions } from '@/common/operation';
 export class ModelHarness {
     /**
      * Strong reasoning agent for high level strategy and planning.
@@ -67,7 +67,9 @@ export class ModelHarness {
         // Scope usage to this invocation, including failed parses and provider
         // retries. A shared cumulative collector can double-count concurrent calls.
         const collector = new Collector('model-call');
+        const finish = beginOperationPhase('model');
         try {
+            checkOperation();
             try {
                 return await invoke(collector);
             }
@@ -98,6 +100,7 @@ export class ModelHarness {
             }
         }
         finally {
+            finish();
             for (const log of collector.logs) {
                 for (const call of log.calls) {
                     try {

package/dist/ai/multiModelHarness.js

@@ -1,6 +1,7 @@
 import { ModelHarness } from "./modelHarness";
 import { allBrowserAgentRoles } from "./types";
 import EventEmitter from "eventemitter3";
+import { drainAll } from '@/common/operation';
 export class MultiModelHarness {
     /**
      * Delegates model responsibilites to different LLMs and consolidates their usage
@@ -11,7 +12,7 @@ export class MultiModelHarness {
     events = new EventEmitter();
     constructor(clients) {
         // Sort by specificity (from least specific to most specific)
-        const sortedClients = clients.toSorted((a, b) => (b.roles ? b.roles.length : 9999) - (a.roles ? a.roles.length : 9999));
+        const sortedClients = [...clients].sort((a, b) => (b.roles ? b.roles.length : 9999) - (a.roles ? a.roles.length : 9999));
         for (const client of sortedClients) {
             const harness = new ModelHarness({ llm: client });
             this.uniqueModels.push(harness);
@@ -30,7 +31,8 @@ export class MultiModelHarness {
         }
     }
     async setup() {
-        await Promise.all(this.uniqueModels.map(model => model.setup()));
+        // A failed model must not release startup while another is still initializing.
+        await drainAll(this.uniqueModels.map(model => model.setup()));
     }
     describe() {
         // for now - describe least specific model

package/dist/common/events.d.ts

@@ -1,7 +1,10 @@
 import { Action } from "@/actions/types";
 import { ActOptions } from "@/agent";
 import { ModelUsage } from "@/ai/types";
+import type { OperationDiagnostics } from './operation';
 export interface AgentEvents {
+    /** Payload-free snapshots. Existing action/thought events retain their original payloads. */
+    'operation': (diagnostics: OperationDiagnostics) => void;
     'start': () => void;
     'stop': () => void;
     'thought': (thought: string) => void;

package/dist/common/operation.d.ts

@@ -3,25 +3,76 @@ export interface OperationOptions {
     /** Absolute Unix time in milliseconds, shared by every step, retry, and wait. */
     deadline?: number;
 }
+export type OperationKind = 'act' | 'query' | 'extract' | 'nav' | 'exec';
+export type OperationPhase = 'preparing' | 'context' | 'observations' | 'model' | 'action' | 'screenshot' | 'stability' | 'cooldown' | 'retry' | 'paused' | 'cursor';
+export interface OperationTiming {
+    count: number;
+    totalMs: number;
+}
+export interface OperationDiagnostics {
+    id: string;
+    kind: OperationKind;
+    status: 'running' | 'draining' | 'finished';
+    outcome?: 'succeeded' | 'failed' | 'cancelled' | 'deadline';
+    phase: OperationPhase;
+    startedAt: number;
+    elapsedMs: number;
+    cancellationToDrainMs?: number;
+    cancellationToIdleMs?: number;
+    lastAction?: {
+        index: number;
+        name: string;
+        state: 'pending' | 'started' | 'completed' | 'failed';
+    };
+    /** Inclusive totals: nested and concurrent phases overlap and must not be summed. */
+    timings: Partial<Record<OperationPhase, OperationTiming>>;
+}
+/** Preserve the original error and add only a payload-free snapshot, when extensible. */
+export declare function attachOperationDiagnostics(error: unknown, diagnostics: OperationDiagnostics): void;
 export declare class Operation {
     readonly owner: object;
-    private options;
+    private kind;
+    private onUpdate?;
     private controller;
     private timer?;
     private closed;
     readonly signal: AbortSignal;
     readonly deadline?: number;
+    private externalSignal?;
     private externalAbort;
-    constructor(owner: object, options: OperationOptions);
+    private readonly id;
+    private readonly startedAt;
+    private readonly started;
+    private finished?;
+    private cancelled?;
+    private idle?;
+    private announced;
+    private outcome?;
+    private lastAction?;
+    private timings;
+    private spans;
+    constructor(owner: object, options: OperationOptions, kind?: OperationKind, onUpdate?: ((diagnostics: OperationDiagnostics) => void) | undefined);
     private scheduleDeadline;
     cancel(reason?: unknown): void;
     check(): void;
     run<T>(fn: () => Promise<T>): Promise<T>;
+    announce(): void;
+    private publish;
+    snapshot(): OperationDiagnostics;
+    beginPhase(phase: OperationPhase): () => void;
+    prepareAction(name: string): void;
+    actionState(state: 'started' | 'completed' | 'failed'): void;
+    fail(error: unknown): void;
+    finish(): void;
+    markIdle(): void;
     dispose(): void;
 }
 export declare function currentOperation(): Operation | undefined;
+export declare function withoutOperation<T>(fn: () => T): T;
 export declare function checkOperation(): void;
 export declare function operationOptions(): OperationOptions;
+export declare function beginOperationPhase(phase: OperationPhase): () => void;
+export declare function measureOperation<T>(phase: OperationPhase, fn: () => Promise<T>): Promise<T>;
 /** Wait for every branch, even when one fails, before releasing the operation. */
 export declare function drainAll<T extends readonly unknown[]>(promises: {
     [K in keyof T]: Promise<T[K]>;