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

package/dist/agent/index.js

@@ -1,505 +0,0 @@
-import logger from '@/logger';
-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 { AgentMemory } from "@/memory";
-import { taskActions } from "@/actions/taskActions";
-import { memoryActions } from '@/actions/memoryActions';
-import { NOTEBOOK_INSTRUCTIONS } from '@/memory/notebook';
-import { traceAsync } from "@/ai/baml_client";
-import { telemetrifyAgent } from '@/telemetry/events';
-import { isClaude } from '@/ai/util';
-import { retryOnError } from '@/common';
-import { renderContentParts } from '@/memory/rendering';
-import { MultiModelHarness } from '@/ai/multiModelHarness';
-// Options for the startAgent helper function
-const DEFAULT_CONFIG = {
-    actions: [...taskActions], // Default to taskActions; other actions come from connectors
-    connectors: [],
-    llm: {
-        provider: 'google-ai',
-        options: {
-            model: 'gemini-2.5-pro-preview-05-06',
-            apiKey: process.env.GOOGLE_API_KEY || "YOUR_GOOGLE_API_KEY"
-        }
-    },
-    prompt: null,
-    telemetry: true,
-    maxActions: Infinity,
-};
-export class Agent {
-    // maybe remove conns/actions from options since stored sep
-    options; //Omit<Required<AgentOptions>, 'actions'>;
-    connectors;
-    actions; // actions from connectors + any other additional ones configured
-    memoryOptions;
-    models;
-    //public readonly model: ModelHarness;
-    //public readonly micro: GroundingService;
-    //public readonly events: EventEmitter<AgentEvents>;
-    //protected readonly _emitter: EventEmitter<AgentEvents>;
-    events = new EventEmitter();
-    //public readonly memory: AgentMemory;
-    doneActing;
-    _paused = false;
-    _pauseResolve = null;
-    activeOperation;
-    idle = Promise.resolve();
-    stopped = false;
-    latestTaskMemory; // | null = null;
-    constructor(baseConfig = {}) {
-        this.options = {
-            ...DEFAULT_CONFIG,
-            ...baseConfig,
-            connectors: baseConfig.connectors ?? [],
-            actions: [...(baseConfig.actions || DEFAULT_CONFIG.actions)],
-        };
-        if (baseConfig.maxActions !== undefined && (!Number.isSafeInteger(baseConfig.maxActions) || baseConfig.maxActions < 1)) {
-            throw new Error('maxActions must be a positive integer');
-        }
-        this.connectors = this.options.connectors;
-        // Aggregate actions from connectors
-        //const aggregatedActions = [...this.options.actions];
-        this.actions = [...this.options.actions];
-        for (const connector of this.connectors) {
-            this.actions.push(...(connector.getActionSpace ? connector.getActionSpace() : []));
-        }
-        for (const action of memoryActions) {
-            if (this.actions.some(existing => existing.name === action.name))
-                throw new Error(`Action name '${action.name}' is reserved for task memory.`);
-            this.actions.push(action);
-        }
-        // Deduplicate actions by name
-        // TODO: maybe error instead, or automatically differentiate them?
-        //this.options.actions = Array.from(new Map(aggregatedActions.map(actDef => [actDef.name, actDef])).values());
-        const llms = Array.isArray(this.options.llm) ? this.options.llm : [this.options.llm];
-        let doPromptCaching = false;
-        for (const client of llms) {
-            // If any LLM is prompt-caching compatible, turn on prompt caching overall for memory etc.
-            if (isClaude(client) && (client.provider === 'anthropic' || client.provider === 'claude-code')) {
-                // Prompt-caching compatible client
-                if ('promptCaching' in client.options && client.options.promptCaching !== undefined) {
-                    doPromptCaching = client.options.promptCaching;
-                }
-                else {
-                    // Default to true if not specified, and override on client config to true
-                    doPromptCaching = true;
-                    client.options.promptCaching = true;
-                }
-            }
-        }
-        //this.model = new ModelHarness({ llm: this.options.llm });
-        this.models = new MultiModelHarness(llms);
-        this.models.events.on('tokensUsed', (usage) => this.events.emit('tokensUsed', usage), this);
-        this.doneActing = false;
-        this._paused = false;
-        this._pauseResolve = null;
-        this.memoryOptions = {
-            // TODO: maybe do if Gemini or other prompt caching supported providers as well
-            // Claude supports prompt caching but only via Anthropic, not on Bedrock
-            promptCaching: doPromptCaching
-        };
-        // Empty memory will get replaced on first act(), but this prevents errors from having undefined memory
-        this.latestTaskMemory = new AgentMemory(this.memoryOptions);
-    }
-    getConnector(connectorClass) {
-        return this.connectors.find(c => c instanceof connectorClass);
-    }
-    require(connectorClass) {
-        const connector = this.getConnector(connectorClass);
-        if (!connector)
-            throw new Error(`Missing required connector ${connectorClass}`);
-        return connector;
-    }
-    async start() {
-        checkOperation();
-        if (this.busy)
-            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
-    }
-    identifyAction(action) {
-        // Get definition corresponding to an action
-        const actionDefinition = this.actions.find(def => def.name === action.variant);
-        if (!actionDefinition) {
-            // It's possible the action name was from a connector that is no longer active,
-            // or the action space was not correctly aggregated.
-            throw new AgentError(`Undefined action type '${action.variant}'. Ensure agent is configured with appropriate action definitions from connectors.`);
-        }
-        return actionDefinition;
-    }
-    /** True until underlying work settles, including after a cancelled caller returns. */
-    get busy() {
-        return this.activeOperation !== undefined;
-    }
-    whenIdle() {
-        return this.idle;
-    }
-    async runOperation(options, fn) {
-        const inherited = currentOperation();
-        if (inherited?.owner === this)
-            inherited.check();
-        if (this.busy)
-            throw new AgentBusyError();
-        if (this.stopped)
-            throw new AgentError('Agent is stopped; call start() before using it');
-        const operation = new Operation(this, options);
-        this.activeOperation = operation;
-        let markIdle;
-        this.idle = new Promise(resolve => { markIdle = resolve; });
-        const worker = operation.run(async () => {
-            operation.check();
-            try {
-                return await fn();
-            }
-            finally {
-                operation.check(); // Preserve the cancellation/deadline cause through downstream errors.
-            }
-        });
-        const settled = worker.finally(() => {
-            operation.dispose();
-            this.activeOperation = undefined;
-            markIdle();
-        });
-        return untilAborted(settled, operation.signal);
-    }
-    async exec(action, memory, options = {}) {
-        return this.runOperation(options, () => this._exec(action, memory));
-    }
-    async _exec(action, memory) {
-        checkOperation();
-        /**
-         * Execute an action that belongs to this Agent's action space.
-         * Provide memory to record the action taken, its results, and any connector observations to that memory.
-         */
-        let actionDefinition = this.identifyAction(action);
-        let input;
-        if (actionDefinition.schema instanceof z.ZodObject) {
-            let variant;
-            ({ variant, ...input } = action);
-        }
-        else {
-            input = action.input;
-        }
-        let parsed = actionDefinition.schema.safeParse(input);
-        if (!parsed.success) {
-            throw new AgentError(`Generated action '${action.variant}' violates input schema: ${parsed.error.message}`, { adaptable: true });
-        }
-        const memoryOnly = memoryActions.includes(actionDefinition);
-        if (!memoryOnly)
-            for (const connector of this.connectors) {
-                await connector.beforeAction?.(action, operationOptions());
-                checkOperation();
-            }
-        this.events.emit('actionStarted', action);
-        checkOperation();
-        const data = await actionDefinition.resolver({ input: parsed.data, agent: this, memory, ...operationOptions() });
-        checkOperation();
-        this.events.emit('actionDone', action);
-        checkOperation();
-        if (memory) {
-            // Record action taken
-            memory.recordObservation(Observation.fromActionTaken(actionDefinition.name, JSON.stringify(action), memoryOnly ? { type: 'notebook-write' } : undefined));
-            // Record results of action
-            if (data) {
-                memory.recordObservation(Observation.fromActionResult(actionDefinition.name, data, memoryOnly ? { type: 'notebook-result', limit: 1 } : undefined));
-            }
-            // Collect and record observations from connectors
-            if (memoryOnly)
-                this.events.emit('observationsRecorded'); // Checkpoint notes without another browser capture.
-            else
-                await this._recordConnectorObservations(memory);
-        }
-        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);
-            }
-        }
-        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));
-    }
-    async _runAct(taskOrSteps, options) {
-        const instructions = [
-            ...(this.options.prompt ? [this.options.prompt] : []),
-            ...(options.prompt ? [options.prompt] : []),
-        ].join('\n');
-        const taskMemory = options.memory ?? new AgentMemory({ ...this.memoryOptions, instructions: instructions === '' ? undefined : instructions });
-        if (Array.isArray(taskOrSteps)) {
-            const steps = taskOrSteps;
-            //this.events.emit('actStarted', steps.join(', '));
-            // trace overall task
-            await (traceAsync('multistep', async (steps, options) => {
-                for (const step of steps) {
-                    checkOperation();
-                    this.events.emit('actStarted', step, options);
-                    await this._traceAct(step, taskMemory, options);
-                    checkOperation();
-                    this.events.emit('actDone', step, options);
-                }
-            })(steps, options));
-            //this.events.emit('actDone', steps.join(', '));
-        }
-        else {
-            const task = taskOrSteps;
-            this.events.emit('actStarted', task, options);
-            await this._traceAct(task, taskMemory, options);
-            checkOperation();
-            this.events.emit('actDone', task, options);
-        }
-    }
-    async _traceAct(task, memory, options = {}) {
-        // memory not serializable to trace so bake it
-        await (traceAsync('act', async (task) => {
-            await this._act(task, memory, options);
-        })(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 {
-            instructions: memory.instructions,
-            observationContent: messages,
-            //observationContent: content,
-            connectorInstructions: connectorInstructions
-        };
-    }
-    async _act(description, memory, options = {}) {
-        checkOperation();
-        this.doneActing = false;
-        for (const connector of this.connectors) {
-            connector.onTaskStart?.(operationOptions());
-            checkOperation();
-        }
-        logger.info(`Act: ${description}`);
-        // for now simply add data to task
-        let dataContentParts = [];
-        if (options.data) {
-            //description += "\nUse the following data where appropriate:\n";
-            // description += "\n<data>\n";
-            // // if (typeof options.data === 'string') {
-            // //     description += options.data;
-            // // } else {
-            // //     description += Object.entries(options.data).map(([k, v]) => `${k}: ${v}`).join("\n");
-            // // }
-            // const parts = renderParts(options.data);
-            // description += "\n</data>";
-            dataContentParts = await renderContentParts(options.data, { mode: 'json', indent: 2 });
-        }
-        //this.events.emit('stepStart', description);
-        //const testData = convertOptionsToTestData(options);
-        // Initialize task memory and record initial observations
-        // Combine any agent-level and task-level instructions
-        checkOperation();
-        this.latestTaskMemory = memory;
-        // record initial observations
-        logger.info("Making initial observations...");
-        await this._recordConnectorObservations(memory);
-        logger.info("Initial observations recorded");
-        let actionCount = 0;
-        while (true) {
-            checkOperation();
-            if (actionCount >= this.options.maxActions)
-                throw new ActionLimitError(this.options.maxActions);
-            // Removed direct screenshot/tabState access here; it's part of memoryContext via connectors
-            logger.info(`Creating partial recipe`);
-            let reasoning = "";
-            let actions = [];
-            let memoryUpdates = [];
-            try {
-                this.events.emit('planningStarted');
-                const memoryContext = await this._buildContext(memory);
-                memoryContext.connectorInstructions.unshift({ connectorId: 'task_memory', instructions: NOTEBOOK_INSTRUCTIONS });
-                await retryOnError(async () => {
-                    ({ reasoning, actions, memory_updates: memoryUpdates } = await this.models.partialAct(memoryContext, description, dataContentParts, this.actions));
-                    checkOperation();
-                    if (actions.length === 0) {
-                        // Empty action list behavior - default wait else ... err? what if not in action space?
-                        //actions.push()
-                        throw new AgentError(`No actions generated`);
-                    }
-                }, 
-                // HTTP body is not JSON - comes from Anthropic sometimes, weird error
-                // Sometimes Anthropic will give 401 Unauthorized randomly even when authorized
-                {
-                    mode: 'retry_on_partial_message',
-                    errorSubstrings: ['HTTP body is not JSON', '401 Unauthorized', 'No actions generated'],
-                    retryLimit: 3,
-                    delayMs: 1000,
-                    showWarnOnRetry: true
-                });
-            }
-            catch (error) {
-                checkOperation();
-                logger.error(`Error planning actions: ${error instanceof Error ? error.message : String(error)}`);
-                /**
-                 * (1) Failure to conform to JSON
-                 * (2) Misconfigured BAML client / bad API key
-                 * (3) Network error (past max retries)
-                 */
-                // this.fail({
-                //     variant: 'misalignment',
-                //     message: `Could not create partial recipe -> ${(error as Error).message}`
-                // });
-                throw new AgentError(`Error planning actions: ${error.message}`, { variant: 'misalignment' });
-            }
-            logger.info({ reasoning, actions }, `Partial recipe created`);
-            // Could be emitted in memory and bubbled up instead of recordThought was called in more places
-            this.events.emit('thought', reasoning);
-            checkOperation();
-            memory.recordThought(reasoning);
-            // Persist the review using the existing audited, budgeted note action.
-            // Empty reviews are free; each attempted write consumes one action.
-            const batch = [...memoryUpdates.map(note => ({ variant: 'memory:note', ...note })), ...actions];
-            for (const action of batch) {
-                await this._waitIfPaused();
-                checkOperation();
-                if (this.doneActing)
-                    break;
-                if (actionCount >= this.options.maxActions)
-                    throw new ActionLimitError(this.options.maxActions);
-                const result = await this._exec(action, memory);
-                actionCount++;
-                // Preserve the current page when an update fails. Successful
-                // earlier writes remain; the next plan sees the failure result.
-                if (action.variant === 'memory:note' && result?.saved === false)
-                    break;
-                // const postActionScreenshot = await this.screenshot();
-                // const actionDescriptor: ActionDescriptor = { ...action, screenshot: postActionScreenshot.image } as ActionDescriptor;
-                // this.events.emit('action', actionDescriptor);
-                logger.info({ action }, `Action taken`);
-            }
-            // If macro expects these actions should complete the step, break
-            // if (finished) {
-            //     break;
-            // }
-            await this._waitIfPaused();
-            if (this.doneActing) {
-                break;
-            }
-        }
-        logger.info(`Done with step`);
-        //this.events.emit('stepSuccess');
-        //this.currentTaskMemory = null;
-    }
-    async query(query, schema, options = {}) {
-        return this.runOperation(options, async () => {
-            // Record observations in case no act() was used beforehand
-            await this._recordConnectorObservations(this.latestTaskMemory);
-            const memoryContext = await this._buildContext(this.memory, options);
-            return await this.models.query(memoryContext, query, schema);
-        });
-    }
-    async queueDone() {
-        checkOperation();
-        this.doneActing = true;
-    }
-    async _waitIfPaused() {
-        checkOperation();
-        if (!this._paused)
-            return;
-        this.events.emit('pause');
-        checkOperation();
-        if (!this._paused)
-            return; // A pause listener may have resumed synchronously.
-        logger.info("Agent: Paused");
-        try {
-            await untilAborted(new Promise((resolve) => {
-                this._pauseResolve = resolve;
-            }), currentOperation()?.signal);
-        }
-        finally {
-            this._pauseResolve = null;
-        }
-    }
-    pause() {
-        checkOperation();
-        this._paused = true;
-    }
-    resume() {
-        checkOperation();
-        this._paused = false;
-        if (this._pauseResolve) {
-            this._pauseResolve();
-            this._pauseResolve = null;
-        }
-        this.events.emit('resume');
-        logger.info("Agent: Resumed");
-    }
-    get paused() {
-        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) {
-            this._paused = false;
-            this._pauseResolve?.();
-            this._pauseResolve = null;
-        }
-        logger.info("Agent: Stopping connectors...");
-        for (const connector of this.connectors) {
-            try {
-                if (connector.onStop)
-                    await connector.onStop();
-            }
-            catch (error) {
-                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/agent/narrator.d.ts

@@ -1,4 +0,0 @@
-import { Agent } from '@/agent';
-import { BrowserAgent } from './browserAgent';
-export declare function narrateAgent(agent: Agent): void;
-export declare function narrateBrowserAgent(agent: BrowserAgent): void;

package/dist/agent/narrator.js

@@ -1,63 +0,0 @@
-import { blueBright, bold, cyanBright, gray } from 'ansis';
-export function narrateAgent(agent) {
-    let totalInputTokens = 0;
-    let totalOutputTokens = 0;
-    let totalCachedWriteInputTokens = 0;
-    let totalCachedReadInputTokens = 0;
-    let totalInputTokenCost = 0.0;
-    let totalOutputTokenCost = 0.0;
-    agent.events.on('tokensUsed', (usage) => {
-        totalInputTokens += usage.inputTokens;
-        totalOutputTokens += usage.outputTokens;
-        totalCachedWriteInputTokens += usage.cacheWriteInputTokens ?? 0;
-        totalCachedReadInputTokens += usage.cacheReadInputTokens ?? 0;
-        totalInputTokenCost += usage.inputCost ?? 0.0;
-        totalOutputTokenCost += usage.outputCost ?? 0.0;
-    });
-    agent.events.on('start', () => {
-        console.log(bold(blueBright(`▶ [start] agent started with ${agent.models.describe()}`)));
-    });
-    agent.events.on('stop', () => {
-        console.log(bold(blueBright(`■ [stop] agent stopped`)));
-        console.log(`  Total usage: ` + bold `${totalInputTokens + totalCachedWriteInputTokens + totalCachedReadInputTokens}` + ` input tokens` + (totalCachedWriteInputTokens > 0 || totalCachedReadInputTokens > 0 ? ` (${totalCachedWriteInputTokens} cache write, ${totalCachedReadInputTokens} cache read)` : '') + ` / ` + bold `${totalOutputTokens}` + ` output tokens`);
-        if (totalInputTokenCost > 0 || totalOutputTokenCost > 0) {
-            if (agent.models.numUniqueModels === 1 && agent.models.describe().startsWith('claude-code')) {
-                console.log(`  Cost: ` + cyanBright `None - using Claude Pro or Max subscription`);
-            }
-            else {
-                console.log(`  Cost: $${(totalInputTokenCost + totalOutputTokenCost).toFixed(3)}`);
-            }
-        }
-        // Show token usage and cost if available
-        // if (totalInputTokenCost > 0 || totalOutputTokenCost > 0) {
-        //     console.log(`  Total usage: ` + bold`${totalInputTokens}` + ` input tokens (` + `$${totalInputTokenCost.toFixed(3)}` + `)` + ` / ` + bold`${totalOutputTokens}` + ` output tokens (` + `$${totalOutputTokenCost.toFixed(3)}` + `)`);
-        // } else {
-        //     console.log(`  Total usage: ` + bold`${totalInputTokens}` + ` input tokens` + ` / ` + bold`${totalOutputTokens}` + ` output tokens`);
-        // }
-    });
-    agent.events.on('thought', (thought) => {
-        console.log(gray `${thought}`);
-        //console.log(gray`⚙︎ ${thought}`);
-    });
-    agent.events.on('actStarted', (task, options) => {
-        console.log(bold(cyanBright(`◆ [act] ${task}`)));
-    });
-    agent.events.on('actionStarted', (action) => {
-        const actionDefinition = agent.identifyAction(action);
-        console.log(bold `  ${actionDefinition.render(action)}`);
-    });
-}
-export function narrateBrowserAgent(agent) {
-    narrateAgent(agent);
-    agent.browserAgentEvents.on('nav', (url) => {
-        console.log(bold(cyanBright `⛓︎ [nav] ${url}`));
-    });
-    agent.browserAgentEvents.on('extractStarted', (instructions, schema) => {
-        console.log(bold(cyanBright `⛏ [extract] ${instructions}`));
-    });
-    agent.browserAgentEvents.on('extractDone', (instructions, data) => {
-        // console.log has a decent default formatter for arbitrary data e.g. objects
-        console.log(data);
-        //console.log(blueBright`${JSON.stringify(data, null, 2)}`);
-    });
-}

package/dist/agent/pause.test.d.ts

@@ -1 +0,0 @@
-export {};