DEV Community: Gil Fink

Architectural Freedom: Implementing LCEL and Composable Chains in Browser AI Agents

Gil Fink — Thu, 25 Jun 2026 12:56:35 +0000

Throughout this series on building enterprise-grade AI agents with Chrome’s Prompt API, we have steadily overcome the major physical limitations of client-side AI. We moved execution to a Web Worker, persisted state with IndexedDB, implemented RAG for dynamic tool retrieval, built autonomous error handling, and conquered token limits with background context compression.

Our engine is robust, but as a framework, it suffered from a classic software engineering anti-pattern: Tight Coupling.

Until now, our agent’s execution logic was hardcoded into a monolithic while loop inside prompt-chain-worker.js. If a developer wanted to build a simple, linear pipeline (e.g., summarize a text, then translate it) rather than a full, autonomous ReAct (Reasoning and Acting) loop, they couldn't. The framework forced every interaction through the complex ReAct cycle.

To elevate prompt-chain from a single-purpose script into a versatile AI framework, we need to decouple the execution topology from the worker host.

Today, we are introducing a Pipeline Architecture inspired by LangChain Expression Language (LCEL). By refactoring our core into modular, composable Runnable components, developers can now pipe prompts into LLMs, attach output parsers, and build custom agent architectures declaratively without ever touching the core web worker code.

The Core Concept: The Runnable Interface

The foundation of LCEL is the Runnable interface. Everything in the system such as prompts, LLM calls, parsers, and even the agent loop itself becomes a Runnable that implements a standard invoke() method.

By standardizing the inputs and outputs, we can chain these components together using RunnableSequence (acting like a pipeline).

The LCEL Primitives

We created a new file to house our base primitives. Here is the implementation of the core Runnable class and the RunnableSequence which allows us to compose chains:

export class Runnable {
    async invoke(input, config = {}) {
        throw new Error("Abstract method invoke() must be implemented.");
    }

    pipe(nextRunnable) {
        if (typeof nextRunnable === "function") {
            nextRunnable = new RunnableLambda(nextRunnable);
        }
        return new RunnableSequence(this, nextRunnable);
    }

    bind(kwargs) {
        return new RunnableBinding(this, kwargs);
    }
}

export class RunnableBinding extends Runnable {
    constructor(boundRunnable, kwargs) {
        super();
        this.boundRunnable = boundRunnable;
        this.kwargs = kwargs;
    }

    async invoke(input, config = {}) {
        return await this.boundRunnable.invoke(input, { ...config, ...this.kwargs });
    }
}

export class RunnableSequence extends Runnable {
    constructor(first, second) {
        super();
        this.first = first;
        this.second = second;
    }

    static from(runnables) {
        if (!Array.isArray(runnables) || runnables.length === 0) {
            throw new Error("RunnableSequence.from expects a non-empty array of runnables.");
        }
        let seq = runnables[0];
        if (typeof seq === "function") seq = new RunnableLambda(seq);

        for (let i = 1; i < runnables.length; i++) {
            let next = runnables[i];
            if (typeof next === "function") next = new RunnableLambda(next);
            seq = seq.pipe(next);
        }
        return seq;
    }

    async invoke(input, config = {}) {
        const firstOutput = await this.first.invoke(input, config);
        return await this.second.invoke(firstOutput, config);
    }
}

export class RunnableParallel extends Runnable {
    constructor(runnablesMap) {
        super();
        this.runnablesMap = runnablesMap;
    }

    async invoke(input, config = {}) {
        const entries = Object.entries(this.runnablesMap);
        const results = await Promise.all(
            entries.map(async ([key, runnable]) => {
                let r = runnable;
                if (typeof r === "function") r = new RunnableLambda(r);
                const output = await r.invoke(input, config);
                return [key, output];
            })
        );
        return Object.fromEntries(results);
    }
}

export class RunnableLambda extends Runnable {
    constructor(func) {
        super();
        this.func = func;
    }

    async invoke(input, config = {}) {
        return await Promise.resolve(this.func(input, config));
    }
}

export class RunnablePassthrough extends Runnable {
    async invoke(input, config = {}) {
        return input;
    }

    static assign(mapping) {
        return new RunnableLambda(async (input, config) => {
            if (typeof input !== "object" || input === null) {
                throw new Error("RunnablePassthrough.assign expects an object input.");
            }
            const parallel = new RunnableParallel(mapping);
            const computedValues = await parallel.invoke(input, config);
            return { ...input, ...computedValues };
        });
    }
}

Alongside these, we implemented RunnableLambda (to wrap arbitrary functions), RunnableParallel (for concurrent execution), and RunnablePassthrough (to carry inputs down the chain).

Refactoring the Architecture

With our primitives in place, we needed to refactor our existing monolithic codebase to conform to this new standard. The first place to start the refactoring was the prompt template implementation.

Upgrading the Prompt Template

Our PromptTemplate previously just returned a string. Now, it extends Runnable, allowing it to sit at the beginning of an LCEL chain. It receives a dictionary of inputs, formats the string, and passes it down the pipeline.

import { Runnable } from "./runnable.js";

export class PromptTemplate extends Runnable {
    constructor() {
        super();
        this.systemInstruction = `You are an autonomous AI agent with long-term memory. Think step-by-step.
            You must STRICTLY output valid JSON matching the schema.

            Rules:
            1. If you need data, set "toolName" to a tool and "toolInput" to the query. Leave "finalAnswer" as "".
            2. If you know the answer, set "toolName" to "none" and put the answer in "finalAnswer".`;

        this.fewShotExamples = `
            --- Example 1: Using a Tool ---
            User: What is the current stock price of Apple?
            {"thought": "I need to look up the real-time stock price for Apple (AAPL).", "toolName": "FetchStockPrice", "toolInput": "AAPL", "finalAnswer": ""}
            Observation from FetchStockPrice: 175.50
            {"thought": "I have the observation. I can now provide the final answer.", "toolName": "none", "toolInput": "", "finalAnswer": "The current stock price of Apple is $175.50."}

            --- Example 2: Answering Directly ---
            User: What is the capital of France?
            {"thought": "I know the capital of France is Paris. No tool is needed.", "toolName": "none", "toolInput": "", "finalAnswer": "The capital of France is Paris."}
            `;
    }

    format(relevantTools, historyTurns, userPrompt, summary = "", skillInstructions = "") {
        const toolDescriptions = relevantTools.length > 0
            ? relevantTools.map(t => `- ${t.name}: ${t.description}`).join('\n')
            : "- none: No external tools available for this query.";

        const summaryPart = summary
            ? `Conversation Summary (Background Context):\n${summary}\n\n`
            : "";

        const skillPart = skillInstructions
            ? `Active Skill Instructions & Guidelines:\n${skillInstructions}\n\n`
            : "";

        return `${this.systemInstruction}           
            Available tools for this request:
            ${toolDescriptions}
            - none: Use this if you do not need a tool.

            ${this.fewShotExamples}

            --- Current Conversation ---
            ${summaryPart}${skillPart}Prior History:
            ${historyTurns.length > 0 ? historyTurns.join('\n') : "No prior history."}

            User: ${userPrompt}
            Output your next step as JSON:`;
    }

    async invoke(input, config = {}) {
        const { relevantTools = [], historyTurns = [], userPrompt = "", summary = "", skillInstructions = "" } = input;
        return this.format(relevantTools, historyTurns, userPrompt, summary, skillInstructions);
    }
}

Componentizing the Inference Step

Previously, calling the LLM and parsing its JSON output was tangled together. We separated these into two distinct Runnable classes inside prompt-chain-worker.js:

export class LLMRunnable extends Runnable {
    constructor(askLLMFn, schema) {
        super();
        this.askLLMFn = askLLMFn;
        this.schema = schema;
    }
    async invoke(prompt, config = {}) {
        return await this.askLLMFn(prompt, this.schema);
    }
}

export class JSONOutputParserRunnable extends Runnable {
    async invoke(responseText, config = {}) {
        try {
            return { success: true, parsed: JSON.parse(responseText) };
        } catch (e) {
            return { success: false, error: "Invalid JSON format received. You must respond strictly in JSON syntax." };
        }
    }
}

By isolating these, we can now construct an inferenceStepChain like this: PromptTemplate -> LLMRunnable -> JSONOutputParserRunnable.

Encapsulating the ReAct Loop

The most complex part of our previous implementation was the runReActLoop function. We encapsulated this entire beast into a dedicated ReActAgentExecutor class that also extends Runnable.

Instead of hardcoding the LLM calls, the Executor now relies on an injected inferenceStepChain.

export class ReActAgentExecutor extends Runnable {
    constructor({ tools = [], skills = [], memory, toolRetriever, skillRetriever, promptTemplate, inferenceStepChain, askLLM, logToMain }) {
        super();
        this.tools = tools;
        this.skills = skills;
        this.memory = memory;
        this.toolRetriever = toolRetriever;
        this.skillRetriever = skillRetriever;
        this.promptTemplate = promptTemplate;
        this.inferenceStepChain = inferenceStepChain;
        this.askLLM = askLLM;
        this.logToMain = logToMain;
    }

    async invoke({ userPrompt, sessionId }) {
        let isComplete = false;
        let finalResult = "";
        let loopCount = 0;

        let { history: historyTurns, summary: conversationSummary } = await this.memory.getHistory(sessionId);

        const relevantTools = await this.toolRetriever.getRelevantTools(userPrompt, 3);
        const relevantSkills = await this.skillRetriever.getRelevantSkills(userPrompt, 3);

        let skillInstructions = "";
        if (relevantSkills.length > 0) {
            for (const skill of relevantSkills) {
                this.logToMain(`System: Activating skill "${skill.name}"`);
                skillInstructions += `${skill.instructions} `;

                for (const skillTool of skill.tools) {
                    if (!relevantTools.some(t => t.name === skillTool.name)) {
                        relevantTools.push(skillTool);
                    }
                }
            }
        }

        const toolsMap = new Map(relevantTools.map(t => [t.name, t]));

        let currentTurnLog = `User: ${userPrompt}\n`;
        let chainInput = { relevantTools, historyTurns, userPrompt, summary: conversationSummary, skillInstructions };

        while (!isComplete && loopCount < 7) {
            loopCount++;

            const stepResult = await this.inferenceStepChain.invoke(chainInput);

            if (!stepResult.success) {
                chainInput = `Observation: ${stepResult.error}`;
                continue;
            }

            const response = stepResult.parsed;

            if (response.thought) {
                this.logToMain(`Thought: ${response.thought}`);
                currentTurnLog += `Thought: ${response.thought}\n`;
            }

            if (response.finalAnswer && response.finalAnswer.trim() !== "") {
                finalResult = response.finalAnswer;
                currentTurnLog += `Assistant: ${response.finalAnswer}\n`;
                isComplete = true;
            }
            else if (response.toolName && response.toolName !== "none" && toolsMap.has(response.toolName)) {
                this.logToMain(`Action: Running ${response.toolName} with input "${response.toolInput}"`);

                const tool = toolsMap.get(response.toolName);
                let toolResult;
                let success = false;
                let retryCount = 0;
                const maxRetries = 3;

                while (retryCount <= maxRetries && !success) {
                    try {
                        toolResult = await runWithTimeout(tool.executeFn, response.toolInput, 3000);
                        success = true;
                    } catch (err) {
                        if (isRecoverableError(err) && retryCount < maxRetries) {
                            retryCount++;
                            this.logToMain(`Observation: Tool timed out. Retrying...`);
                            await delay(1000);
                        } else {
                            currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: Tool failed with error: ${err.message}\n`;
                            this.logToMain(`Observation: Tool failed with error: ${err.message}`);
                            chainInput = `Observation: Tool '${response.toolName}' failed because: ${err.message}. Please correct the input/parameters, try a different approach, or check tool availability, and try again.`;
                            break;
                        }
                    }
                }

                if (success) {
                    currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: ${toolResult}\n`;
                    this.logToMain(`Observation: ${toolResult}`);
                    chainInput = `Observation from ${response.toolName}: ${toolResult}\nGiven this observation, output your next step as JSON:`;
                }
            }
            else if (response.toolName === "none" || response.toolName === "") {
                chainInput = `Observation: You set toolName to "none" but omitted a finalAnswer. Provide your final answer text in the JSON.`;
            }
            else {
                chainInput = `Observation: Tool '${response.toolName}' is not loaded. Select from available tools or use 'none'.`;
            }
        }

        if (finalResult) {
            historyTurns.push(currentTurnLog.trim());
            const compressionResult = await compressHistory(historyTurns, conversationSummary, this.askLLM, this.logToMain);
            await this.memory.saveHistory(sessionId, compressionResult.historyTurns, compressionResult.updatedSummary);
        }

        return finalResult || "Error: Reached maximum iterations.";
    }
}

The Universal Agent Runtime

The final piece of the puzzle is the web worker entry point: createAgentWorker. It is now a polymorphic, universal runtime host.

If you pass it an array of tools (the legacy way), it automatically wires up the default ReActAgentExecutor. But, if you pass it a custom Runnable chain, it completely bypasses the ReAct logic and executes your custom topology.

export function createAgentWorker(toolsOrRunnable, skillsArray = []) {
    let msgId = 0;
    const resolvers = new Map();

    const memory = new AgentMemory();

    const agentSchema = {
        "type": "object",
        "properties": {
            "thought": { "type": "string" },
            "toolName": { "type": "string" },
            "toolInput": { "type": "string" },
            "finalAnswer": { "type": "string" }
        },
        "required": ["thought", "toolName", "toolInput", "finalAnswer"]
    };

    function askLLM(prompt, schema = agentSchema) {
        return new Promise((resolve, reject) => {
            const id = ++msgId;
            resolvers.set(id, { resolve, reject });
            self.postMessage({ id, type: MessageContext.llmRequest, payload: { prompt, schema } });
        });
    }

    function logToMain(message) {
        self.postMessage({ id: 0, type: MessageContext.agentLog, payload: message });
    }

    let agentExecutor;
    if (toolsOrRunnable instanceof Runnable || typeof toolsOrRunnable?.invoke === "function") {
        agentExecutor = toolsOrRunnable;
    } else {
        const toolsArray = Array.isArray(toolsOrRunnable) ? toolsOrRunnable : [];
        const toolRetriever = new ToolRetriever(toolsArray);
        const skillRetriever = new SkillRetriever(skillsArray);
        const promptTemplate = new PromptTemplate();

        const llmRunnable = new LLMRunnable(askLLM, agentSchema);
        const parserRunnable = new JSONOutputParserRunnable();

        const inferenceStepChain = RunnableSequence.from([
            new RunnableLambda(async (promptInput) => {
                if (typeof promptInput === "string") return promptInput;
                return await promptTemplate.invoke(promptInput);
            }),
            llmRunnable,
            parserRunnable
        ]);

        agentExecutor = new ReActAgentExecutor({
            tools: toolsArray,
            skills: skillsArray,
            memory,
            toolRetriever,
            skillRetriever,
            promptTemplate,
            inferenceStepChain,
            askLLM,
            logToMain
        });
    }

    self.addEventListener('message', async (e) => {
        const { id, type, payload } = e.data;

        if (type === MessageContext.llmResponse) {
            resolvers.get(id)?.resolve(payload);
            resolvers.delete(id);
        } else if (type === MessageContext.llmError) {
            resolvers.get(id)?.reject(new Error(payload));
            resolvers.delete(id);
        } else if (type === MessageContext.startLoop) {
            try {
                await memory.init();
                const answer = await agentExecutor.invoke({
                    userPrompt: payload.userPrompt,
                    sessionId: payload.sessionId,
                    memory,
                    askLLM,
                    logToMain
                });
                const finalStr = typeof answer === "string" ? answer : answer?.finalAnswer || JSON.stringify(answer);
                self.postMessage({ id, type: MessageContext.agentComplete, payload: finalStr });
            } catch (err) {
                self.postMessage({ id, type: MessageContext.agentError, payload: err.message });
            }
        }
    });
}

Summary

This refactoring completely changes the trajectory of the prompt-chain project.

By adopting the LCEL pattern, we are no longer forcing developers into a single cognitive architecture. If you want to bypass the ReAct loop entirely and just run a fast, linear classification pipeline directly in the browser’s background thread, you can define a RunnableSequence and pass it right into the worker.

Modularity brings freedom. By explicitly separating prompt formatting, LLM execution, output parsing, and the looping mechanism, we have built a highly extensible foundation for whatever browser-native AI topologies developers dream up next.

If you are interested in the code, you can find it on my Github — https://github.com/gilf/prompt-chain.

Injecting On-Demand Domain Expertise: Building a Dynamic Skills Feature for Browser AI Agents

Gil Fink — Sat, 20 Jun 2026 13:18:23 +0000

In our ongoing series on engineering enterprise-grade AI agents using Chrome’s built-in Prompt API, we have successfully conquered performance, persistence, prompt stabilization, and memory compression.

Our core background agent engine is rock solid. But as we move from basic utilities toward a real, production-ready AI platform, we hit a product engineering wall: monolithic scope creep.

Up until now, if you wanted your agent to learn a new capability, you had to hardcode more tools into the engine and expand the core system instructions. If you want your agent to write SQL, parse medical data, or check the weather, your master prompt gets heavier, your token consumption spikes, and smaller on-device models like Gemini Nano begin to hallucinate under the cognitive load of unrelated instructions.

Today, we are introducing a transformative pattern to solve this: dynamic skills retrieval and execution.

Instead of building a monolithic “know-it-all” AI, we have updated our library to support modular, self-contained skills that are retrieved on demand, injecting domain-specific markdown instructions and local tools into the ReAct loop only when the user’s intent requires it.

Why Modular Skills are Critical for Client-Side AI?

When deploying agents inside consumer browsers, optimizing resources is the name of the game. Modularity isn’t just an aesthetic choice, it’s a strict architectural requirement for three distinct reasons:

Context window optimization: on-device models have smaller active context constraints than massive cloud endpoints. Swapping domain instructions in and out dynamically keeps our active token overhead highly streamlined.
Decoupled extensions: developers or different teams can build, package, and deploy specialized skills entirely independently. A skill is simply an isolated folder containing a manifest file (SKILL.md) and its operational tools (tools.js) served over HTTP.
Model shielding: smaller models perform exponentially better when given fewer choices. By presenting the agent with only the active tools required for the task at hand, we drastically lower the risk of structural tool-calling failures.

The Architectural Blueprint

To make this work, we introduced a dynamic loader that parses standard Markdown frontmatter, a standalone keyword-scoring skill retriever, and an updated ReAct loop inside our web worker that plugs tools at runtime.

The Skill Manifest & Dynamic Loader

A skill is defined by an individual folder served on your network. It contains a SKILL.md file featuring a simple YAML frontmatter configuration block for metadata, followed by deep instructions for the LLM.

To keep the library completely independent of heavy npm packages, we implemented a fast, lightweight regex frontmatter parser and dynamic file loader:

import { Tool } from './prompt-chain-worker.js';

export class Skill {
    constructor(name, description, instructions, tools = []) {
        this.name = name;
        this.description = description;
        this.instructions = instructions;
        this.tools = tools;
    }
}

export function parseFrontmatter(markdown) {
    const regex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
    const match = markdown.match(regex);
    if (!match) {
        return { attributes: {}, body: markdown };
    }

    const yamlStr = match[1];
    const body = match[2];
    const attributes = {};
    const lines = yamlStr.split('\n');

    for (const line of lines) {
        const parts = line.split(':');
        if (parts.length >= 2) {
            const key = parts[0].trim();
            attributes[key] = parts.slice(1).join(':').trim().replace(/^['"]|['"]$/g, '');;
        }
    }

    return { attributes, body };
}

export async function loadSkillFromUrl(baseUrl) {
    const cleanBaseUrl = baseUrl.replace(/\/$/, '');

    const skillMdUrl = `${cleanBaseUrl}/SKILL.md`;
    const res = await fetch(skillMdUrl);
    if (!res.ok) {
        throw new Error(`Failed to load skill manifest from ${skillMdUrl}`);
    }
    const markdown = await res.text();
    const { attributes, body } = parseFrontmatter(markdown);

    const name = attributes.name || "UnnamedSkill";
    const description = attributes.description || "";
    const instructions = body.trim();

    let tools = [];
    try {
        const toolsUrl = `${cleanBaseUrl}/tools.js`;
        const module = await import(toolsUrl);
        const rawTools = module.tools || module.default || [];
        if (Array.isArray(rawTools)) {
            tools = rawTools.map(t => new Tool(t.name, t.description, t.executeFn));
        }
    } catch (err) {
        console.warn(`Could not load tools for skill ${name}:`, err);
    }

    return new Skill(name, description, instructions, tools);
}

The Intent Routing Layer

To evaluate if an available skill is relevant to what the user requested, we added a dedicated SkillRetriever. This class implements a token overlap scoring metric matching tokens against the skill's declared title and semantic description block:

export class SkillRetriever {
    constructor(skillsArray = []) {
        this.skills = skillsArray;
    }

    async getRelevantSkills(userPrompt, topK = 1) {
        if (this.skills.length <= topK) return this.skills;

        const query = userPrompt.toLowerCase();

        const scoredSkills = this.skills.map(skill => {
            let score = 0;
            const targetText = `${skill.name} ${skill.description}`.toLowerCase();
            const queryTokens = query.split(/\W+/);
            for (const token of queryTokens) {
                if (token.length > 3 && targetText.includes(token)) {
                    score += 1;
                }
            }
            return { skill, score };
        });

        return scoredSkills
            .filter(item => item.score > 0)
            .sort((a, b) => b.score - a.score)
            .slice(0, topK)
            .map(item => item.skill);
    }
}

Hot-Plugging the Web Worker Engine

Next, we stitch the skill retrieval, custom instruction payload compilation, and dynamic runtime tool injection into the worker’s orchestration layers.

First, update PromptTemplate to cleanly host the custom skill instructions segment inside the top-level template context:

export class PromptTemplate {
    constructor() {
        this.systemInstruction = `You are an autonomous AI agent with long-term memory. Think step-by-step.
            You must STRICTLY output valid JSON matching the schema.

            Rules:
            1. If you need data, set "toolName" to a tool and "toolInput" to the query. Leave "finalAnswer" as "".
            2. If you know the answer, set "toolName" to "none" and put the answer in "finalAnswer".`;

        this.fewShotExamples = `
            --- Example 1: Using a Tool ---
            User: What is the current stock price of Apple?
            {"thought": "I need to look up the real-time stock price for Apple (AAPL).", "toolName": "FetchStockPrice", "toolInput": "AAPL", "finalAnswer": ""}
            Observation from FetchStockPrice: 175.50
            {"thought": "I have the observation. I can now provide the final answer.", "toolName": "none", "toolInput": "", "finalAnswer": "The current stock price of Apple is $175.50."}

            --- Example 2: Answering Directly ---
            User: What is the capital of France?
            {"thought": "I know the capital of France is Paris. No tool is needed.", "toolName": "none", "toolInput": "", "finalAnswer": "The capital of France is Paris."}
            `;
    }

    format(relevantTools, historyTurns, userPrompt, summary = "", skillInstructions = "") {
        const toolDescriptions = relevantTools.length > 0
            ? relevantTools.map(t => `- ${t.name}: ${t.description}`).join('\n')
            : "- none: No external tools available for this query.";

        const summaryPart = summary
            ? `Conversation Summary (Background Context):\n${summary}\n\n`
            : "";

        const skillPart = skillInstructions
            ? `Active Skill Instructions & Guidelines:\n${skillInstructions}\n\n`
            : "";

        return `${this.systemInstruction}           
            Available tools for this request:
            ${toolDescriptions}
            - none: Use this if you do not need a tool.

            ${this.fewShotExamples}

            --- Current Conversation ---
            ${summaryPart}${skillPart}Prior History:
            ${historyTurns.length > 0 ? historyTurns.join('\n') : "No prior history."}

            User: ${userPrompt}
            Output your next step as JSON:`;
    }
}

Then, modify prompt-chain-worker.js to look up relevant skills and hot-swap their bundled tools into the current active execution maps before starting the loop cycles:

import { MessageContext } from "./consts.js";
import { AgentMemory } from "./agent-memory.js";
import { PromptTemplate } from "./prompt-template.js";
import { ToolRetriever } from "./tool-retriever.js";
import { SkillRetriever } from "./skill-retriever.js";
import { isRecoverableError, runWithTimeout, delay, compressHistory } from "./utils.js";

export class Tool {
    constructor(name, description, executeFn) {
        this.name = name;
        this.description = description;
        this.executeFn = executeFn;
    }
}

export function createAgentWorker(toolsArray, skillsArray = []) {
    let msgId = 0;
    const resolvers = new Map();

    const memory = new AgentMemory();
    const toolRetriever = new ToolRetriever(toolsArray);
    const skillRetriever = new SkillRetriever(skillsArray);
    const promptTemplate = new PromptTemplate();

    const agentSchema = {
        "type": "object",
        "properties": {
            "thought": { "type": "string" },
            "toolName": { "type": "string" },
            "toolInput": { "type": "string" },
            "finalAnswer": { "type": "string" }
        },
        "required": ["thought", "toolName", "toolInput", "finalAnswer"]
    };

    function askLLM(prompt, schema = agentSchema) {
        return new Promise((resolve, reject) => {
            const id = ++msgId;
            resolvers.set(id, { resolve, reject });
            self.postMessage({ id, type: MessageContext.llmRequest, payload: { prompt, schema } });
        });
    }

    function logToMain(message) {
        self.postMessage({ id: 0, type: MessageContext.agentLog, payload: message });
    }

    async function runReActLoop(userPrompt, sessionId) {
        let isComplete = false;
        let finalResult = "";
        let loopCount = 0;

        let { history: historyTurns, summary: conversationSummary } = await memory.getHistory(sessionId);

        const relevantTools = await toolRetriever.getRelevantTools(userPrompt, 3);
        const relevantSkills = await skillRetriever.getRelevantSkills(userPrompt, 3);

        let skillInstructions = "";
        if (relevantSkills.length > 0) {
            for (const skill of relevantSkills) {
                logToMain(`System: Activating skill "${skill.name}"`);
                skillInstructions =+ `${skill.instructions} `;

                for (const skillTool of skill.tools) {
                    if (!relevantTools.some(t => t.name === skillTool.name)) {
                        relevantTools.push(skillTool);
                    }
                }
            }
        }

        const toolsMap = new Map(relevantTools.map(t => [t.name, t]));

        let currentTurnLog = `User: ${userPrompt}\n`;
        let currentPrompt = promptTemplate.format(relevantTools, historyTurns, userPrompt, conversationSummary, skillInstructions);

        while (!isComplete && loopCount < 7) {
            loopCount++;

            const responseText = await askLLM(currentPrompt);
            let response;

            try {
                response = JSON.parse(responseText);
            } catch (e) {
                currentPrompt = `Observation: Invalid JSON format received. You must respond strictly in JSON syntax.`;
                continue;
            }

            if (response.thought) {
                logToMain(`Thought: ${response.thought}`);
                currentTurnLog += `Thought: ${response.thought}\n`;
            }

            if (response.finalAnswer && response.finalAnswer.trim() !== "") {
                finalResult = response.finalAnswer;
                currentTurnLog += `Assistant: ${response.finalAnswer}\n`;
                isComplete = true;
            }
            else if (response.toolName && response.toolName !== "none" && toolsMap.has(response.toolName)) {
                logToMain(`Action: Running ${response.toolName} with input "${response.toolInput}"`);

                const tool = toolsMap.get(response.toolName);
                let toolResult;
                let success = false;
                let retryCount = 0;
                const maxRetries = 3;

                while (retryCount <= maxRetries && !success) {
                    try {
                        toolResult = await runWithTimeout(tool.executeFn, response.toolInput, 3000);
                        success = true;
                    } catch (err) {
                        if (isRecoverableError(err) && retryCount < maxRetries) {
                            retryCount++;
                            logToMain(`Observation: Tool timed out. Retrying...`);
                            await delay(1000);
                        } else {
                            currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: Tool failed with error: ${err.message}\n`;
                            logToMain(`Observation: Tool failed with error: ${err.message}`);
                            currentPrompt = `Observation: Tool '${response.toolName}' failed because: ${err.message}. Please correct the input/parameters, try a different approach, or check tool availability, and try again.`;
                            break;
                        }
                    }
                }

                if (success) {
                    currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: ${toolResult}\n`;
                    logToMain(`Observation: ${toolResult}`);
                    currentPrompt = `Observation from ${response.toolName}: ${toolResult}\nGiven this observation, output your next step as JSON:`;
                }
            }
            else if (response.toolName === "none" || response.toolName === "") {
                currentPrompt = `Observation: You set toolName to "none" but omitted a finalAnswer. Provide your final answer text in the JSON.`;
            }
            else {
                currentPrompt = `Observation: Tool '${response.toolName}' is not loaded. Select from available tools or use 'none'.`;
            }
        }

        if (finalResult) {
            historyTurns.push(currentTurnLog.trim());
            const compressionResult = await compressHistory(historyTurns, conversationSummary, askLLM, logToMain);
            await memory.saveHistory(sessionId, compressionResult.historyTurns, compressionResult.updatedSummary);
        }

        return finalResult || "Error: Reached maximum iterations.";
    }

    self.addEventListener('message', async (e) => {
        const { id, type, payload } = e.data;

        if (type === MessageContext.llmResponse) {
            resolvers.get(id)?.resolve(payload);
            resolvers.delete(id);
        } else if (type === MessageContext.llmError) {
            resolvers.get(id)?.reject(new Error(payload));
            resolvers.delete(id);
        } else if (type === MessageContext.startLoop) {
            try {
                await memory.init();
                const answer = await runReActLoop(payload.userPrompt, payload.sessionId);
                self.postMessage({ id, type: MessageContext.agentComplete, payload: answer });
            } catch (err) {
                self.postMessage({ id, type: MessageContext.agentError, payload: err.message });
            }
        }
    });
}

Creating an Isolated Skill Module: WeatherExpert

To verify the design, we can implement an independent skill folder inside a static directory (/skills/weather/).

We define the custom behavior rules inside SKILL.md:

---
name: WeatherExpert
description: Retrieve current weather forecasts, temperatures, and conditions for a specific city.
---

# WeatherExpert Instructions
You are the WeatherExpert assistant. When the user asks about the weather or forecast for a specific city, follow these rules:
1. Identify the city or location the user is asking about.
2. Call the "GetWeather" tool with the city name as the input parameter.
3. Once you receive the weather details, summarize the temperature, wind speed, and condition in a friendly, conversational tone.
4. Format the final output nicely (e.g., using bullet points for key weather stats) and add a cheerful sign-off.

And define its local mockup function behavior inside tools.js:

export const tools = [
    {
        name: "GetWeather",
        description: "Fetches current weather information for a given city.",
        executeFn: async (city) => {
            const mockWeather = {
                "london": "15°C, Light rain, Wind 12km/h, Humidity 82%",
                "new york": "22°C, Sunny, Wind 8km/h, Humidity 45%",
                "tokyo": "26°C, Humid and Partly Cloudy, Wind 5km/h, Humidity 70%",
                "paris": "19°C, Partly Cloudy, Wind 10km/h, Humidity 55%",
                "sydney": "18°C, Clear, Wind 15km/h, Humidity 60%",
                "berlin": "17°C, Overcast, Wind 9km/h, Humidity 75%"
            };

            const normalized = city.trim().toLowerCase();
            for (const key of Object.keys(mockWeather)) {
                if (normalized.includes(key)) {
                    return mockWeather[key];
                }
            }
            return `20°C, Clear Sky, Wind 7km/h (Default forecast for ${city})`;
        }
    }
];

Now, instead of mixing this domain logic with our core engine, the client instantiation code in my-agent.js can cleanly load it dynamically over HTTP:

import { Tool, createAgentWorker } from './prompt-chain-worker.js';
import { loadSkillFromUrl } from './skill.js';

const fetchTool = new Tool(
    "FetchData",
    "Fetches text content from a URL.",
    async (url) => {
        const res = await fetch(url);
        if (!res.ok) {
            throw new Error(`HTTP Error: status ${res.status}`);
        }
        return await res.text();
    }
);

const mathTool = new Tool(
    "Calculator",
    "Evaluates math expressions (e.g. '100 * 5').",
    (expression) => {
        return String(eval(expression));
    }
);

const weatherSkill = await loadSkillFromUrl('./skills/weather');
createAgentWorker([fetchTool, mathTool], [weatherSkill]);

Summary

The update we introduced alters the capabilities of our client-side web agents. When a user asks a calculation query like “Calculate 542 * 13”, the intent matcher leaves the system context clean, executing purely with the global calculator tools.

However, the second the user interacts with a “Weather in Tokyo” prompt, the worker intercepts the stream, pushes the WeatherExpert skill live, seamlessly binds the GetWeather async function, and enforces the unique bulleted layout instructions and friendly tone explicitly outlined in the localized manifest.

We have successfully migrated from building a simple client-side text wrapper to designing a highly scalable, dynamic plugin architecture for localized edge intelligence.

If you are interested in the code, you can find it on my Github — https://github.com/gilf/prompt-chain.

Escaping the Token Limit: Context Compression and Infinite Memory for Browser AI Agents

Gil Fink — Fri, 19 Jun 2026 12:26:23 +0000

In our ongoing series on building enterprise-grade AI agents directly in the browser, we’ve tackled some serious architectural hurdles. We offloaded the heavy ReAct loop to Web Workers to save the main thread, added IndexedDB for persistence, implemented RAG for dynamic tool retrieval, and built autonomous retry logic to handle inevitable systemic failures.

Our agent is now fast, stateful, and highly resilient. But as users engage with our agent in longer, more complex sessions, we hit a hard physical limitation of on-device AI: the context window.

Local models like Chrome’s built-in Gemini Nano are incredibly powerful, but they have strict token limits. Up until now, our AgentMemory implementation used a simple sliding window, keeping only the last 10 conversational turns and blindly dropping the rest.

The problem? If a user tells the agent their dietary preferences on Turn 1, and asks for a recipe on Turn 12, the agent has completely forgotten the constraints. Truncation causes amnesia.

Today, we are going to solve this by introducing context compression via summarization. We will recursively summarize the conversation in the background, allowing the agent to maintain theoretically infinite memory without ever blowing out the prompt API’s token limits.

The Architecture of Context Compression

The concept is straightforward, but requires careful orchestration within our web worker. Instead of simply pushing raw text into an array until it overflows, we introduce a background compression cycle.

Here is the strategy to do that:

The threshold: We let the raw conversation history grow up to a specific limit (e.g., 5 turns).
The summarization prompt: Once the threshold is hit, we pause and construct a new prompt entirely in the background. We ask the LLM to read the existing summary plus the new raw turns, and generate a combined, updated summary.
The recency buffer: We keep the updated summary as our “long-term background context” and retain only the last 1 or 2 raw turns for immediate, short-term conversational flow.
Persistence: We save both the summary and the truncated history back to IndexedDB.

Let’s dive into the implementation.

Upgrading IndexedDB for Summaries

First, we need to update our AgentMemory class to support storing and retrieving a summary string alongside the raw history array. Because IndexedDB is a NoSQL object store, this schema change is completely seamless.

export class AgentMemory {
    constructor(dbName = "AgentMemoryDB", storeName = "conversations") {
        this.dbName = dbName;
        this.storeName = storeName;
        this.db = null;
    }

    init() {
        return new Promise((resolve, reject) => {
            const request = indexedDB.open(this.dbName, 1);

            request.onupgradeneeded = (e) => {
                const db = e.target.result;
                if (!db.objectStoreNames.contains(this.storeName)) {
                    db.createObjectStore(this.storeName, { keyPath: "sessionId" });
                }
            };

            request.onsuccess = (e) => {
                this.db = e.target.result;
                resolve();
            };

            request.onerror = (e) => reject(e.target.error);
        });
    }

    getHistory(sessionId) {
        return new Promise((resolve) => {
            const tx = this.db.transaction(this.storeName, "readonly");
            const store = tx.objectStore(this.storeName);
            const request = store.get(sessionId);

            request.onsuccess = () => {
                if (request.result) {
                    resolve({
                        history: request.result.history || [],
                        summary: request.result.summary || ""
                    });
                } else {
                    resolve({ history: [], summary: "" });
                }
            };
            request.onerror = () => resolve({ history: [], summary: "" });
        });
    }

    saveHistory(sessionId, history, summary = "") {
        return new Promise((resolve, reject) => {
            const tx = this.db.transaction(this.storeName, "readwrite");
            const store = tx.objectStore(this.storeName);
            const request = store.put({ sessionId, history, summary });

            request.onsuccess = () => resolve();
            request.onerror = (e) => reject(e.target.error);
        });
    }
}

The Compression Engine

Next, we build the core logic for the compression. This function needs access to the askLLM helper from our worker so it can trigger a background prompt.

Notice a critical architectural detail here: when we call askLLM(summaryPrompt, null), we pass null for the JSON schema. While our main ReAct loop relies on strict JSON to execute tools, summarization is a pure text-generation task. We drop the schema constraint to let the model write freely.

export async function compressHistory(historyTurns, conversationSummary, askLLM, logToMain) {
    const SUMMARIZATION_THRESHOLD = 5;
    const RECENCY_TURNS_TO_KEEP = 2;

    if (historyTurns.length < SUMMARIZATION_THRESHOLD) {
        return { historyTurns, updatedSummary: conversationSummary };
    }

    logToMain("Summarizing conversation context to compress memory...");
    let summaryPrompt = "";
    if (conversationSummary) {
        summaryPrompt = `Based on the following existing summary and the new conversation history, write an updated, concise summary that retains all key facts, decisions, and user preferences.
            Existing Summary:
            ${conversationSummary}

            New Conversation History:
            ${historyTurns.join('\n')}

            Output only the updated summary text. Do not output JSON.`;
    } else {
        summaryPrompt = `Based on the following conversation history, write a concise summary that retains all key facts, decisions, and user preferences.
            Conversation History:
            ${historyTurns.join('\n')}

            Output only the summary text. Do not output JSON.`;
    }

    let updatedSummary = conversationSummary;
    let updatedHistory = historyTurns;
    try {
        const rawSummary = await askLLM(summaryPrompt, null);
        updatedSummary = rawSummary.trim();
        logToMain(`New Conversation Summary: ${updatedSummary}`);
        updatedHistory = historyTurns.slice(-RECENCY_TURNS_TO_KEEP);
    } catch (err) {
        logToMain(`Failed to summarize conversation: ${err.message}. Saving history without summarization.`);
    }

    return { historyTurns: updatedHistory, updatedSummary };
}

This function exists in the utils.js file.

Injecting the Summary into the Prompt

With the summary generated, we must ensure the agent is actually aware of it during its reasoning phase. We update our PromptTemplate to inject the summary right above the immediate conversational history.

export class PromptTemplate {
    constructor() {
        this.systemInstruction = `You are an autonomous AI agent with long-term memory. Think step-by-step.
            You must STRICTLY output valid JSON matching the schema.

            Rules:
            1. If you need data, set "toolName" to a tool and "toolInput" to the query. Leave "finalAnswer" as "".
            2. If you know the answer, set "toolName" to "none" and put the answer in "finalAnswer".`;

        this.fewShotExamples = `
            --- Example 1: Using a Tool ---
            User: What is the current stock price of Apple?
            {"thought": "I need to look up the real-time stock price for Apple (AAPL).", "toolName": "FetchStockPrice", "toolInput": "AAPL", "finalAnswer": ""}
            Observation from FetchStockPrice: 175.50
            {"thought": "I have the observation. I can now provide the final answer.", "toolName": "none", "toolInput": "", "finalAnswer": "The current stock price of Apple is $175.50."}

            --- Example 2: Answering Directly ---
            User: What is the capital of France?
            {"thought": "I know the capital of France is Paris. No tool is needed.", "toolName": "none", "toolInput": "", "finalAnswer": "The capital of France is Paris."}
            `;
    }

    format(relevantTools, historyTurns, userPrompt, summary = "") {
        const toolDescriptions = relevantTools.length > 0
            ? relevantTools.map(t => `- ${t.name}: ${t.description}`).join('\n')
            : "- none: No external tools available for this query.";

        const summaryPart = summary
            ? `Conversation Summary (Background Context):\n${summary}\n\n`
            : "";

        return `${this.systemInstruction}           
            Available tools for this request:
            ${toolDescriptions}
            - none: Use this if you do not need a tool.

            ${this.fewShotExamples}

            --- Current Conversation ---
            ${summaryPart}Prior History:
            ${historyTurns.length > 0 ? historyTurns.join('\n') : "No prior history."}

            User: ${userPrompt}
            Output your next step as JSON:`;
    }
}

Closing the Loop in the Worker

Finally, we tie it all together in our runReActLoop. Because we've already abstracted the heavy lifting, the integration here is incredibly clean. We fetch the summary at the start of the loop, pass it to the template, and then compress the history right before saving.

async function runReActLoop(userPrompt, sessionId) {
    let isComplete = false;
    let finalResult = "";
    let loopCount = 0;

    let { history: historyTurns, summary: conversationSummary } = await memory.getHistory(sessionId);
    const relevantTools = await toolRetriever.getRelevantTools(userPrompt, 3);
    const toolsMap = new Map(relevantTools.map(t => [t.name, t]));

    let currentTurnLog = `User: ${userPrompt}\n`;
    let currentPrompt = promptTemplate.format(relevantTools, historyTurns, userPrompt, conversationSummary);

    while (!isComplete && loopCount < 7) {
        loopCount++;

        const responseText = await askLLM(currentPrompt);
        let response;

        try {
            response = JSON.parse(responseText);
        } catch (e) {
            currentPrompt = `Observation: Invalid JSON format received. You must respond strictly in JSON syntax.`;
            continue;
        }

        if (response.thought) {
            logToMain(`Thought: ${response.thought}`);
            currentTurnLog += `Thought: ${response.thought}\n`;
        }

        if (response.finalAnswer && response.finalAnswer.trim() !== "") {
            finalResult = response.finalAnswer;
            currentTurnLog += `Assistant: ${response.finalAnswer}\n`;
            isComplete = true;
        }
        else if (response.toolName && response.toolName !== "none" && toolsMap.has(response.toolName)) {
            logToMain(`Action: Running ${response.toolName} with input "${response.toolInput}"`);

            const tool = toolsMap.get(response.toolName);
            let toolResult;
            let success = false;
            let retryCount = 0;
            const maxRetries = 3;

            while (retryCount <= maxRetries && !success) {
                try {
                    toolResult = await runWithTimeout(tool.executeFn, response.toolInput, 3000);
                    success = true;
                } catch (err) {
                    if (isRecoverableError(err) && retryCount < maxRetries) {
                        retryCount++;
                        logToMain(`Observation: Tool timed out. Retrying...`);
                        await delay(1000);
                    } else {
                        currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: Tool failed with error: ${err.message}\n`;
                        logToMain(`Observation: Tool failed with error: ${err.message}`);
                        currentPrompt = `Observation: Tool '${response.toolName}' failed because: ${err.message}. Please correct the input/parameters, try a different approach, or check tool availability, and try again.`;
                        break;
                    }
                }
            }

            if (success) {
                currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: ${toolResult}\n`;
                logToMain(`Observation: ${toolResult}`);
                currentPrompt = `Observation from ${response.toolName}: ${toolResult}\nGiven this observation, output your next step as JSON:`;
            }
        }
        else if (response.toolName === "none" || response.toolName === "") {
            currentPrompt = `Observation: You set toolName to "none" but omitted a finalAnswer. Provide your final answer text in the JSON.`;
        }
        else {
            currentPrompt = `Observation: Tool '${response.toolName}' is not loaded. Select from available tools or use 'none'.`;
        }
    }

    if (finalResult) {
        historyTurns.push(currentTurnLog.trim());
        const compressionResult = await compressHistory(historyTurns, conversationSummary, askLLM, logToMain);
        await memory.saveHistory(sessionId, compressionResult.historyTurns, compressionResult.updatedSummary);
    }

    return finalResult || "Error: Reached maximum iterations.";
}

Summary

By implementing this background compression cycle, we have effectively uncoupled our agent’s memory capacity from the prompt window’s physical limitations.

The main thread remains completely unblocked. The agent retains long-term user preferences in a highly compressed format, while keeping the last few turns completely raw to ensure the conversational interaction feels natural and responsive.

Building robust front-end architectures isn’t just about managing the DOM anymore, it’s about managing state, asynchronous orchestration, and now, LLM token economics.

If you are interested in the code, you can find it on my Github — https://github.com/gilf/prompt-chain.

Making the Browser Agent Resilient: Implementing Autonomous Error Handling and Retries

Gil Fink — Thu, 18 Jun 2026 08:47:36 +0000

In the previous installments of our series on building browser-based AI agents, we tackled performance by offloading the reasoning loop to Web Workers, achieved persistence using IndexedDB, and mastered contextual intelligence using local RAG and few-shot prompting.

Our agent is fast, stateful, and intelligent. But in the messy, real world of front-end development, intelligence is not enough . To build truly autonomous systems, we must also build for resilience.

Until now, our agent loop made a fatal architectural assumption: it assumed that once the LLM decided to use a tool, that tool would execute perfectly, every time. As front-end developers, we know this is a naive dream. APIs time out, network requests fail with 500s, and third-party scripts crash. If your agent is truly autonomous, it must have a mechanism to recover from these failures on its own, before ever reporting back to the user with a broken result.

Today, we will implement autonomous error handling and retry logic right inside our ReAct loop.

The Architectural Mandate for Autonomy

When an AI agent’s tool execution fails, we need to classify that failure into two categories to determine the best approach:

Recoverable Errors (Systemic): These are transient, recoverable errors like a temporary network hiccup (HTTP 502/503), a tool execution timing out, or a rate limit (HTTP 429). In these scenarios, the agent should not give up. It should autonomously decide to wait and retry , because there’s a high probability the next call will succeed.
Persistent Errors (Model Hallucinations/Logic Bugs): These are errors that retrying will not fix. This includes the model hallucinating a tool that doesn’t exist, providing incorrect parameters that crash a function, or a genuine bug in our tool’s implementation. In this scenario, retrying is a waste of resources. Instead, we must capture the error and feed it back into the model’s context window as an Observation. This forces the agent to autonomously reason: "My last action failed with this specific error message. I must now regenerate my plan, correct my parameters, or try a different approach entirely."

This system of retrying systemic failures and self-correcting logic failures is essential for enterprise-grade autonomy.

The Toolbox

To make our implementation clean and maintainable, we first create a set of essential helper functions in a new utils.js file, completely separate from the core agent engine.

export function isRecoverableError(error) {
    const msg = error.message.toLowerCase();
    return (
        msg.includes("timeout") ||
        msg.includes("time out") ||
        msg.includes("fetch") ||
        msg.includes("network") ||
        msg.includes("http error") ||
        msg.includes("status 5") ||
        msg.includes("status 429") ||
        msg.includes("rate limit") ||
        error.name === "TimeoutError"
    );
}

export async function runWithTimeout(executeFn, input, timeoutMs = 3000) {
    return new Promise((resolve, reject) => {
        const timer = setTimeout(() => {
            const err = new Error("Tool execution timed out.");
            err.name = "TimeoutError";
            reject(err);
        }, timeoutMs);

        Promise.resolve(executeFn(input))
            .then(result => {
                clearTimeout(timer);
                resolve(result);
            })
            .catch(err => {
                clearTimeout(timer);
                reject(err);
            });
    });
}

export function delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

This toolkit allows us to enforce time limits on tool calls, categorize failures as transient or critical, and wait before retrying, all essential patterns for building resilient systems on top of asynchronous native APIs.

Integrating in the Loop

Now, we integrate this logic directly into our web worker’s core ReAct agent loop runReActLoop. We must replace the simple, direct tool execution with a robust while (retryCount <= maxRetries && !success) loop structure. This new block handles the classification and response to any tool execution failure entirely inside the background thread.

async function runReActLoop(userPrompt, sessionId) {
    let isComplete = false;
    let finalResult = "";
    let loopCount = 0;

    const historyTurns = await memory.getHistory(sessionId);
    const relevantTools = await toolRetriever.getRelevantTools(userPrompt, 3);
    const toolsMap = new Map(relevantTools.map(t => [t.name, t]));

    let currentTurnLog = `User: ${userPrompt}\n`;
    let currentPrompt = promptTemplate.format(relevantTools, historyTurns, userPrompt);

    while (!isComplete && loopCount < 7) {
        loopCount++;

        const responseText = await askLLM(currentPrompt);
        let response;

        try {
            response = JSON.parse(responseText);
        } catch (e) {
            currentPrompt = `Observation: Invalid JSON format received. You must respond strictly in JSON syntax.`;
            continue;
        }

        if (response.thought) {
            logToMain(`Thought: ${response.thought}`);
            currentTurnLog += `Thought: ${response.thought}\n`;
        }

        if (response.finalAnswer && response.finalAnswer.trim() !== "") {
            finalResult = response.finalAnswer;
            currentTurnLog += `Assistant: ${response.finalAnswer}\n`;
            isComplete = true;
        }
        else if (response.toolName && response.toolName !== "none" && toolsMap.has(response.toolName)) {
            logToMain(`Action: Running ${response.toolName} with input "${response.toolInput}"`);

            const tool = toolsMap.get(response.toolName);
            let toolResult;
            let success = false;
            let retryCount = 0;
            const maxRetries = 3;

            while (retryCount <= maxRetries && !success) {
                try {
                    toolResult = await runWithTimeout(tool.executeFn, response.toolInput, 3000);
                    success = true;
                } catch (err) {
                    if (isRecoverableError(err) && retryCount < maxRetries) {
                        retryCount++;
                        logToMain(`Observation: Tool timed out. Retrying...`);
                        await delay(1000);
                    } else {
                        currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: Tool failed with error: ${err.message}\n`;
                        logToMain(`Observation: Tool failed with error: ${err.message}`);
                        currentPrompt = `Observation: Tool '${response.toolName}' failed because: ${err.message}. Please correct the input/parameters, try a different approach, or check tool availability, and try again.`;
                        break;
                    }
                }
            }

            if (success) {
                currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: ${toolResult}\n`;
                logToMain(`Observation: ${toolResult}`);
                currentPrompt = `Observation from ${response.toolName}: ${toolResult}\nGiven this observation, output your next step as JSON:`;
            }
        }
        else if (response.toolName === "none" || response.toolName === "") {
            currentPrompt = `Observation: You set toolName to "none" but omitted a finalAnswer. Provide your final answer text in the JSON.`;
        }
        else {
            currentPrompt = `Observation: Tool '${response.toolName}' is not loaded. Select from available tools or use 'none'.`;
        }
    }

    if (finalResult) {
        historyTurns.push(currentTurnLog.trim());
        if (historyTurns.length > 10) historyTurns.shift();
        await memory.saveHistory(sessionId, historyTurns);
    }

    return finalResult || "Error: Reached maximum iterations.";
}

Summary

By merging our first-turn full prompt with stateful conversational delta prompting, few-shot templates, RAG tool retrieval, and now, an error handling and retry mechanism, we have built an nice robust architectural pattern.

We are no longer just asking Chrome’s Prompt API to perform text generation. We have built an Autonomous Agent Platform. Our browser agent is not just growing up, it’s now resilient enough to face the challenges of a production environment.

What else do you think I should add to the implementation to make the implementation even better?

If you are interested in the code, you can find it on my Github — https://github.com/gilf/prompt-chain.

Scaling Front-End AI Agents: RAG for Tools and Escaping the Infinite Loop

Gil Fink — Tue, 16 Jun 2026 08:17:38 +0000

In our journey to build an enterprise-grade AI agent directly in the browser, we have laid a solid foundation. In Part 1, we tackled performance by offloading the ReAct reasoning loop into Web Workers. In Part 2, we cured our agent’s “goldfish memory” by implementing a persistent, cross-thread IndexedDB storage layer.

Our agent is fast and it remembers. But as we start adding more tools and giving it more complex tasks, two massive structural problems emerge: Context Window Exhaustion and the dreaded Infinite Tool Loop.

Today, we are going to fix both. We will evolve our architecture by introducing a Retrieval-Augmented Generation (RAG) pattern for our tools, and we will stabilize the on-device model’s reasoning using Few-Shot Prompting and Conversational Delta Prompting.

Challenge 1: The Context Window Scalability Problem

When we first built our agent, we hardcoded the tool descriptions directly into the system prompt. If you have two tools (Calculator and FetchData), this works fine.

But what happens when your application scales? What if you have 50 specialized tools for checking user permissions, parsing CSVs, querying local databases, and triggering UI modals?

If you dump 50 tool descriptions into the prompt, two things can happen:

You exhaust the token limit. Smaller on-device models like Gemini Nano have strict context windows.
You confuse the model. The model struggles to find the “signal in the noise,” leading to hallucinated tool calls.

The Solution: A Lightweight Tool Retriever (RAG)

Instead of giving the model every tool, we should only give it the tools relevant to the user’s current request. This is a localized version of RAG (Retrieval-Augmented Generation).

To solve this, we introduce the ToolRetriever class into our web worker.

class ToolRetriever {
    constructor(toolsArray) {
        this.tools = toolsArray;
    }

    // A lightweight retrieval mechanism to find the top K relevant tools
    async getRelevantTools(userPrompt, topK = 3) {
        if (this.tools.length <= topK) return this.tools;

        const query = userPrompt.toLowerCase();

        // Score tools based on relevance to the prompt
        const scoredTools = this.tools.map(tool => {
            let score = 0;
            const targetText = (tool.name + " " + tool.description).toLowerCase();

            // Basic token overlap scoring (Simulating a BM25 or Embedding search)
            const queryTokens = query.split(/\W+/);
            for (const token of queryTokens) {
                if (token.length > 3 && targetText.includes(token)) {
                    score += 1;
                }
            }
            return { tool, score };
        });

        return scoredTools
            .sort((a, b) => b.score - a.score)
            .slice(0, topK)
            .map(st => st.tool);
    }
}

By filtering our tools down to the topK (e.g., the top 3), we keep the prompt lean and focused. If a developer registers 100 tools, the model only ever sees the 3 that actually matter for the specific task at hand which will make the context thiner and result in a more accurate responses from the model.

Challenge 2: The Infinite Tool Loop

If you have spent any time building ReAct agents, you have likely encountered the infinite loop. It looks like this:

Thought: I need to calculate 542 * 13.

Action: Calculator(“542 * 13”)

Observation: 7046

Thought: I need to calculate 542 * 13.

Action: Calculator(“542 * 13”) (…repeats until max iterations reached)

Why does this happen? It boils down to Context Recency Bias and Format Mismatch. Smaller models struggle with zero-shot JSON generation. When we just throw data at them, they lose track of the conversation structure, ignore the Observation, and default back to trying to solve the original user prompt over and over again.

The Solution: Prompt Templates & Few-Shot Examples

To fix this, we must rigidly structure how the model perceives its own actions. We do this by creating a PromptTemplate class.

Instead of trusting the model to figure out the JSON format, we provide Few-Shot Examples. We explicitly show it what a successful tool interaction looks like. Notice the --- Execution Trace --- block below, this is critical for helping the model differentiate between user input and its own past actions.

class PromptTemplate {
    constructor() {
        this.systemInstruction = `You are an autonomous AI agent with long-term memory. Think step-by-step.
            You must STRICTLY output valid JSON matching the schema.

            Rules:
            1. If you need data, set "toolName" to a tool and "toolInput" to the query. Leave "finalAnswer" as "".
            2. If you know the answer, set "toolName" to "none" and put the answer in "finalAnswer".`;

        this.fewShotExamples = `
            --- Example 1: Using a Tool ---
            User: What is the current stock price of Apple?
            --- Execution Trace ---
            {"thought": "I need to look up the real-time stock price for Apple (AAPL).", "toolName": "FetchStockPrice", "toolInput": "AAPL", "finalAnswer": ""}
            Observation from FetchStockPrice: 175.50
            {"thought": "I have the observation. I can now provide the final answer.", "toolName": "none", "toolInput": "", "finalAnswer": "The current stock price of Apple is $175.50."}

            --- Example 2: Answering Directly ---
            User: What is the capital of France?
            {"thought": "I know the capital of France is Paris. No tool is needed.", "toolName": "none", "toolInput": "", "finalAnswer": "The capital of France is Paris."}
            `;
    }

    format(relevantTools, historyTurns, userPrompt) {
        const toolDescriptions = relevantTools.length > 0
            ? relevantTools.map(t => `- ${t.name}: ${t.description}`).join('\n')
            : "- none: No external tools available for this query.";

        return `${this.systemInstruction}           
            Available tools for this request:
            ${toolDescriptions}
            - none: Use this if you do not need a tool.

            ${this.fewShotExamples}

            --- Current Conversation ---
            Prior History:
            ${historyTurns.length > 0 ? historyTurns.join('\n') : "No prior history."}

            User: ${userPrompt}
            Output your next step as JSON:`;
    }
}

The Master Stroke: Conversational Delta Prompting

Even with the template, there is one final hurdle. The Chrome Prompt API is inherently a stateful, conversational API. If we send that massive PromptTemplate into the model on every single loop iteration, the model gets confused by seeing the massive instruction set repeated mid-conversation.

We must switch to Conversational Delta Prompting.

Turn 1: We send the massive PromptTemplate (Instructions, Tools, Examples, User Prompt).
Turn 2 (and beyond): We only send the observation back to the model.

Because Chrome’s API maintains the session state, the model remembers the instructions from Turn 1. Here is how we update the core runReActLoop to support this:

async function runReActLoop(userPrompt, sessionId) {
    let isComplete = false;
    let finalResult = "";
    let loopCount = 0;

    const historyTurns = await memory.getHistory(sessionId);
    const relevantTools = await toolRetriever.getRelevantTools(userPrompt, 3);
    const toolsMap = new Map(relevantTools.map(t => [t.name, t]));

    let currentTurnLog = `User: ${userPrompt}\n`;
    let currentPrompt = promptTemplate.format(relevantTools, historyTurns, userPrompt);

    while (!isComplete && loopCount < 7) {
        loopCount++;

        const responseText = await askLLM(currentPrompt);
        let response;

        try {
            response = JSON.parse(responseText);
        } catch (e) {
            currentPrompt = `Observation: Invalid JSON format received. You must respond strictly in JSON syntax.`;
            continue;
        }

        if (response.thought) {
            logToMain(`Thought: ${response.thought}`);
            currentTurnLog += `Thought: ${response.thought}\n`;
        }

        if (response.finalAnswer && response.finalAnswer.trim() !== "") {
            finalResult = response.finalAnswer;
            currentTurnLog += `Assistant: ${response.finalAnswer}\n`;
            isComplete = true;
        }
        else if (response.toolName && response.toolName !== "none" && toolsMap.has(response.toolName)) {
            logToMain(`Action: Running ${response.toolName} with input "${response.toolInput}"`);

            try {
                const tool = toolsMap.get(response.toolName);
                const toolResult = await tool.executeFn(response.toolInput);

                currentTurnLog += `Action: ${response.toolName}("${response.toolInput}")\nObservation: ${toolResult}\n`;
                logToMain(`Observation: ${toolResult}`);
                currentPrompt = `Observation from ${response.toolName}: ${toolResult}\nGiven this observation, output your next step as JSON:`;

            } catch (err) {
                currentTurnLog += `Observation: Tool failed with error: ${err.message}\n`;
                currentPrompt = `Observation: Tool failed with error: ${err.message}\nGiven this observation, output your next step as JSON:`;
            }
        }
        else if (response.toolName === "none" || response.toolName === "") {
            currentPrompt = `Observation: You set toolName to "none" but omitted a finalAnswer. Provide your final answer text in the JSON.`;
        }
        else {
            currentPrompt = `Observation: Tool '${response.toolName}' is not loaded. Select from available tools or use 'none'.`;
        }
    }

    if (finalResult) {
        historyTurns.push(currentTurnLog.trim());
        if (historyTurns.length > 10) historyTurns.shift();
        await memory.saveHistory(sessionId, historyTurns);
    }

    return finalResult || "Error: Reached maximum iterations.";
}

Summary

By combining a localized RAG Tool Retriever with strict Few-Shot Templates and Conversational Delta Prompting , we have transformed a brittle proof-of-concept into a more reliable agent engine.

It can now handle hundreds of registered tools without blowing the token limit, and it gracefully processes multi-step tool interactions without falling into infinite, amnesiac loops.

Our browser-based agent is growing up.

If you are interested in the code, you can find it on my Github — https://github.com/gilf/prompt-chain.

Adding to Your On-Device Agent Long-Term Memory: Integrating IndexedDB into Chrome’s Prompt API

Gil Fink — Mon, 15 Jun 2026 06:38:45 +0000

In my previous post, we explored how to build a stateless, LangChain-style agent architecture using the Chrome Prompt API and Web Workers. We successfully offloaded the “heavy lifting”, the ReAct reasoning loop, JSON parsing, and tool execution, into background threads to keep the UI smooth.

But there was a catch. Our agent was essentially a “goldfish.” Every time you called runAgent, it started with a blank slate. It had no recollection of the previous turn, the user's preferences, or the results of a tool call from five minutes ago. To build truly sophisticated web-based AI tools, we need Persistence.

Today, let’s evolve that architecture by adding a memory layer using the browser’s native IndexedDB , and see why this is the missing piece for truly autonomous in-browser agents.

The Challenge: Where to Store the Past?

When working with Web Workers, your storage options are surprisingly limited. You cannot use localStorage or sessionStorage effectively because they are synchronous and the can’t be used inside a web worker.

The solution is IndexedDB.

IndexedDB is asynchronous, transactional, and crucially accessible from both the main thread and web workers. This allows our agent to persist its conversation history directly from the background thread, without ever interrupting the UI’s main execution loop.

The Architectural Change

To integrate memory, we need to move from a stateless “request-response” model to a “session-based” model.

The Memory Layer: A dedicated class to handle the IndexedDB transaction logic.
Context Loading: Before the ReAct loop starts, the worker fetches the history associated with a specific sessionId and injects it into the prompt.
Incremental Updates: After each successful agent run, the worker commits the updated conversation state back to the database.

The Memory Manager

Here is the implementation of our AgentMemory class. We keep this generic so it can be used across different agent implementations.

class AgentMemory {
    constructor(dbName = "AgentMemoryDB", storeName = "conversations") {
        this.dbName = dbName;
        this.storeName = storeName;
        this.db = null;
    }

    init() {
        return new Promise((resolve, reject) => {
            const request = indexedDB.open(this.dbName, 1);

            request.onupgradeneeded = (e) => {
                const db = e.target.result;
                if (!db.objectStoreNames.contains(this.storeName)) {
                    // Keyed by sessionId (e.g., "session_123")
                    db.createObjectStore(this.storeName, { keyPath: "sessionId" });
                }
            };

            request.onsuccess = (e) => {
                this.db = e.target.result;
                resolve();
            };

            request.onerror = (e) => reject(e.target.error);
        });
    }

    getHistory(sessionId) {
        return new Promise((resolve) => {
            const tx = this.db.transaction(this.storeName, "readonly");
            const store = tx.objectStore(this.storeName);
            const request = store.get(sessionId);

            request.onsuccess = () => {
                resolve(request.result ? request.result.history : []);
            };
            request.onerror = () => resolve([]);
        });
    }

    saveHistory(sessionId, history) {
        return new Promise((resolve, reject) => {
            const tx = this.db.transaction(this.storeName, "readwrite");
            const store = tx.objectStore(this.storeName);
            const request = store.put({ sessionId, history });

            request.onsuccess = () => resolve();
            request.onerror = (e) => reject(e.target.error);
        });
    }
}

Updating the ReAct Loop

The true power of this implementation lies in how we bridge the memory layer with the Prompt API. We don’t just “dump” the history into the prompt. We manage it as part of the context window.

In our runReActLoop, we fetch the history and include it in the context string. This gives the Gemini Nano model a "working memory" of what happened previously.

async function runReActLoop(userPrompt, sessionId) {
        let isComplete = false;
        let finalResult = "";
        let loopCount = 0;

        // Load historical turns from IndexedDB entirely in the background
        const historyTurns = await memory.getHistory(sessionId);

        const toolDescriptions = toolsArray.map(t => `- ${t.name}: ${t.description}`).join('\n');

        // Inject instructions, available tools, and historical conversation
        let context = `System: You are an AI agent with long-term memory. Think step-by-step.
Available tools:
${toolDescriptions}
- none: Use this if you do not need a tool and can answer the user directly.

Rules:
1. If you need data, set "toolName" to a tool and "toolInput" to the query. Leave "finalAnswer" as "".
2. If you know the answer, set "toolName" to "none" and put the answer in "finalAnswer".

Prior Conversation History:
${historyTurns.length > 0 ? historyTurns.join('\n') : "No prior history."}

Current Turn:
User: ${userPrompt}\n`;

        // Local turn buffer to record the ongoing ReAct execution sequence
        let currentTurnLog = `User: ${userPrompt}\n`;

        while (!isComplete && loopCount < 7) {
            loopCount++;

            const responseText = await askLLM(`${context}\nOutput your next step as JSON:`);
            let response;

            try {
                response = JSON.parse(responseText);
            } catch (e) {
                context += `Observation: Invalid JSON format. Please output strictly valid JSON.\n`;
                continue;
            }

            if (response.thought) {
                logToMain(`Thought: ${response.thought}`);
                currentTurnLog += `Thought: ${response.thought}\n`;
            }

            if (response.finalAnswer && response.finalAnswer.trim() !== "") {
                finalResult = response.finalAnswer;
                currentTurnLog += `Assistant: ${response.finalAnswer}\n`;
                isComplete = true;
            }
            else if (response.toolName && response.toolName !== "none" && toolsMap.has(response.toolName)) {
                logToMain(`Action: Running ${response.toolName} with input "${response.toolInput}"`);

                try {
                    const tool = toolsMap.get(response.toolName);
                    const toolResult = await tool.executeFn(response.toolInput);

                    const actionStr = `Action: ${response.toolName}("${response.toolInput}")\nObservation: ${toolResult}\n`;
                    context += actionStr;
                    currentTurnLog += actionStr;

                    logToMain(`Observation: ${toolResult}`);
                } catch (err) {
                    context += `Observation: Tool failed with error: ${err.message}\n`;
                }
            }
            else if (response.toolName === "none" || response.toolName === "") {
                context += `Observation: You selected no tools, but didn't provide a finalAnswer. Please provide the final answer.\n`;
            }
            else {
                context += `Observation: Tool '${response.toolName}' does not exist. Use an available tool or 'none'.\n`;
            }
        }

        // Persist updated history back to IndexedDB before wrapping up
        if (finalResult) {
            historyTurns.push(currentTurnLog.trim());
            // Optional: keep the sliding window under control (e.g., last 10 full turns)
            if (historyTurns.length > 10) historyTurns.shift();
            await memory.saveHistory(sessionId, historyTurns);
        }

        return finalResult || "Error: Reached maximum iterations.";
    }

    // Handle incoming commands
    self.addEventListener('message', async (e) => {
        const { id, type, payload } = e.data;

        if (type === 'llm_response') {
            resolvers.get(id)?.resolve(payload);
            resolvers.delete(id);
        } else if (type === 'llm_error') {
            resolvers.get(id)?.reject(new Error(payload));
            resolvers.delete(id);
        } else if (type === 'start_loop') {
            try {
                // Ensure IndexedDB is initialized before running the ReAct loop
                await memory.init();
                const answer = await runReActLoop(payload.userPrompt, payload.sessionId);
                self.postMessage({ id, type: 'agent_complete', payload: answer });
            } catch (err) {
                self.postMessage({ id, type: 'agent_error', payload: err.message });
            }
        }
    });

The Performance Trade-off

One architectural concern here is Context Window Inflation. If a user chats with your agent for a lot of time, the conversation history will eventually exceed the token limit of the on-device model.

In the implementation above, I added a simple sliding window logic:

// Optional: keep the sliding window under control (e.g., last 10 full turns)
if (historyTurns.length > 10) historyTurns.shift();
await memory.saveHistory(sessionId, historyTurns);

Summary

By delegating the memory management to the worker thread and using IndexedDB, we have achieved three critical goals:

Thread Safety: The UI thread knows nothing about the storage mechanism. It simply passes a sessionId.
Resilience: Because the history is persisted in IndexedDB, the agent “remembers” the conversation even after a page refresh.
Isolation: By using a sessionId, we can support multi-tenant agents in a single browser tab. Users can switch between different chat contexts without conflict.

This is exactly how enterprise-grade browser applications should handle AI state. We aren’t just building a chatbot, we are building an autonomous system that respects the browser’s constraints while delivering a sophisticated, stateful experience.

If you are interested in the code, you can find it on my Github — https://github.com/gilf/prompt-chain.

Building a LangChain-Style AI Agent in the Browser Using Chrome’s Prompt API and Web Workers

Gil Fink — Tue, 09 Jun 2026 07:28:36 +0000

In the dynamic world of front-end development, the tools and APIs available to us are constantly evolving. For years, integrating AI into a web application meant relying on heavy server-side processing, expensive API calls to cloud providers, and dealing with the inherent latency of network requests. Today, a significant shift is occurring, and AI is moving to the edge, directly into the user’s browser.

Google Chrome’s new Prompt API, powered by the on-device Gemini Nano model, is a gamechanger. It allows front-end developers to run natural language processing tasks locally, ensuring privacy, zero-latency inference, and offline capabilities. However, providing a user with an empty text box and asking an on-device model to “do everything” rarely yields enterprise-grade results. To build truly smart, autonomous applications, we need Agents.

In this comprehensive guide, we will explore how to build a robust, LangChain-style AI agent architecture entirely in the browser. We will tackle the architectural challenges of running AI on the UI thread, leverage Web Workers for heavy lifting, and implement the ReAct (Reason + Act) pattern to give our on-device model the ability to use custom tools.

The Architectural Challenge: AI on the Main Thread

Before we dive into the code, we must address the elephant in the room: performance.

As front-end architects, we know that the browser’s main thread is responsible for everything the user interacts with rendering the DOM, handling click events, executing JavaScript, and painting pixels to the screen. When you introduce a computationally heavy task to the main thread, the UI freezes. This phenomenon, known as “Jank,” degrades the user experience significantly.

While Gemini Nano is highly optimized for edge devices, querying a Language Learning Model (LLM) is still a heavy asynchronous operation. If we were to run a complex, multi-step agent loop (where the model thinks, acts, observes, and thinks again) entirely on the main thread, the browser would struggle to maintain a smooth 60 frames per second (FPS).

The Web Worker Dilemma

The standard solution for offloading heavy computations in the browser is the Web Worker. Web Workers allow you to run JavaScript in background threads, separate from the UI.

However, as of the current implementation in Chrome, the Prompt API window.LanguageModel is not available inside Web Workers. This limitation stems from the complexity of establishing Permission Policies (like checking if a site is allowed to run the model) across different execution contexts.

The Proxy Architecture Solution

To solve this, we must implement a Proxy Architecture.

The Main Thread: Acts as the “LLM Server.” It holds the actual window.ai session and listens for prompts.
The Web Worker: Acts as the “Agent Orchestrator.” It runs the heavy logic loop, executes background tools (like fetching data or parsing large strings), and uses Remote Procedure Calls (RPC) via postMessage to ask the Main Thread for LLM completions.

This decoupling ensures that our application remains incredibly responsive, even when the agent is executing a 10 step chain of thought.

Borrowing from LangChain: The ReAct Pattern

To make our on-device model autonomous, we will borrow a concept popularized by frameworks like LangChain: the ReAct (Reason + Act) pattern.

Traditional prompting involves asking a question and getting a static answer. Agentic prompting involves giving the model a goal, a set of tools, and a structured loop to follow.

In the ReAct pattern, the LLM acts as the routing engine. When given a prompt, it enters a while loop:

Reason (Thought): The model evaluates the current state and decides what it needs to do next.
Act (Action): The model selects a tool from its available arsenal and provides the input for that tool.
Observe (Observation): The system executes the tool, captures the output, and feeds it back to the model.
Repeat: The model reasons about the new observation until it can formulate a Final Answer.

Enforcing Structure with JSON Schemas

Large cloud models can often follow ReAct instructions via plain text prompts. However, smaller on-device models like Gemini Nano require stricter guardrails.

To prevent the model from hallucinating tool names or outputting unstructured text, we utilize the responseConstraint feature of the Prompt API. By passing a JSON Schema to the API, we force the model to output strict, deterministically parsable JSON on every iteration.

Step 1: The Main Thread Host

Let’s start building. The first piece of our architecture is the PromptChainHost. This class lives on the main thread. Its sole responsibility is to instantiate the Web Worker, initialize the Gemini Nano session, and act as a bridge between the background agent and the Prompt API.

import { MessageContext } from "./consts.js";

export class PromptChainHost {
    constructor(workerUrl) {
        this.worker = new Worker(workerUrl, { type: 'module' });
        this.session = null;
        this.callbacks = new Map();
        this.msgId = 0;

        this.worker.onmessage = this.handleWorkerMessage.bind(this);
    }

    async init(systemPrompt) {
        this.session = await LanguageModel.create({
            systemPrompt: systemPrompt
        });
    }

    async handleWorkerMessage(e) {
        const { id, type, payload } = e.data;

        if (type === MessageContext.llmRequest) {
            try {
                // Force the LLM to output JSON so we can parse tool requests
                const responseText = await this.session.prompt(payload.prompt, {
                    responseConstraint: payload.schema
                });
                this.worker.postMessage({ id, type: MessageContext.llmResponse, payload: responseText });
            } catch (err) {
                this.worker.postMessage({ id, type: MessageContext.llmError, payload: err.message });
            }
        }
        else if (type === 'agent_log') {
            window.dispatchEvent(new CustomEvent(MessageContext.agentLog, { detail: payload }));
        }
        else if (type === MessageContext.agentComplete) {
            const cb = this.callbacks.get(id);
            if (cb) {
                cb.resolve(payload);
            }
            this.callbacks.delete(id);
        }
        else if (type === MessageContext.agentError) {
            const cb = this.callbacks.get(id);
            if (cb) {
                cb.reject(new Error(payload));
            }
            this.callbacks.delete(id);
        }
    }

    runAgent(userPrompt) {
        return new Promise((resolve, reject) => {
            const id = ++this.msgId;
            this.callbacks.set(id, { resolve, reject });
            this.worker.postMessage({ id, type: MessageContext.startLoop, payload: userPrompt });
        });
    }
}

Architectural Nuances of the Host

Notice how thin this layer is. The host does not know what tools exist, it does not parse JSON, and it does not handle any business logic. By keeping the main thread lean, we ensure that the browser’s rendering engine has maximum resources available. The window.dispatchEvent mechanism is particularly useful here, as it allows us to decouple the core logic from our React, Angular, or Vanilla JS components.

Step 2: The Worker Core Engine

This is the heart of our library. Because we cannot pass JavaScript functions (tools) via postMessage due to the browser’s Structured Clone algorithm, we create a generic worker engine. Developers will import this file into their own worker scripts to define their tools.

This file handles the while loop, manages the conversation context string, parses the JSON, and manually triggers the functions.

import { MessageContext } from "./consts.js";

export class Tool {
    constructor(name, description, executeFn) {
        this.name = name;
        this.description = description;
        this.executeFn = executeFn;
    }
}

export function createAgentWorker(toolsArray, maxIterations = 7) {
    let msgId = 0;
    const resolvers = new Map();
    const toolsMap = new Map(toolsArray.map(t => [t.name, t]));

    // Schema to force the LLM to choose between thinking, acting, or answering
    const agentSchema = {
        "type": "object",
        "properties": {
            "thought": { "type": "string", "description": "Reasoning for the current step." },
            "toolName": { "type": "string", "description": "Name of tool to use. Empty if no tool needed." },
            "toolInput": { "type": "string", "description": "Input for the tool." },
            "finalAnswer": { "type": "string", "description": "The final answer. Empty if using a tool." }
        },
        "required": ["thought", "toolName", "toolInput", "finalAnswer"],
    };

    function askLLM(prompt) {
        return new Promise((resolve, reject) => {
            const id = ++msgId;
            resolvers.set(id, { resolve, reject });
            self.postMessage({ id, type: MessageContext.llmRequest, payload: { prompt, schema: agentSchema } });
        });
    }

    function logToMain(message) {
        self.postMessage({ id: 0, type: MessageContext.agentLog, payload: message });
    }

    async function runReActLoop(userPrompt) {
        let isComplete = false;
        let finalResult = "";
        let loopCount = 0;

        // Inject available tools into the conversation context
        const toolDescriptions = toolsArray.map(t => `- ${t.name}: ${t.description}`).join('\n');
        let context = `System: You are an AI agent. Think step-by-step.
            Available tools:
            ${toolDescriptions}
            - none: Use this if you do not need a tool and can answer the user directly.

            Rules:
            1. If you need data, set "toolName" to a tool and "toolInput" to the query. Leave "finalAnswer" as "".
            2. If you know the answer, set "toolName" to "none" and put the answer in "finalAnswer".

            Conversation:
            User: ${userPrompt}\n`;

        while (!isComplete && loopCount < maxIterations) {
            loopCount++;

            const responseText = await askLLM(`${context}\nOutput your next step as JSON:`);
            let response;
            try {
                response = JSON.parse(responseText);
            } catch (e) {
                context += `Observation: Invalid JSON format. Please output strictly valid JSON.\n`;
                continue;
            }

            if (response.thought) {
                logToMain(`Thought: ${response.thought}`);
            }

            if (response.finalAnswer && response.finalAnswer.trim() !== "") {
                finalResult = response.finalAnswer;
                isComplete = true;
            } else if (response.toolName && response.toolName !== "none" && toolsMap.has(response.toolName)) {
                logToMain(`Action: Running ${response.toolName} with input "${response.toolInput}"`);

                try {
                    const tool = toolsMap.get(response.toolName);
                    const toolResult = await tool.executeFn(response.toolInput);

                    context += `Action: ${response.toolName}("${response.toolInput}")\n`;
                    context += `Observation: ${toolResult}\n`;
                    logToMain(`Observation: ${toolResult}`);
                } catch (err) {
                    context += `Observation: Tool failed with error: ${err.message}\n`;
                }
            } else if (response.toolName === "none" || response.toolName === "") {
                // Edge case: Model selected none, but forgot to populate finalAnswer
                context += `Observation: You selected no tools, but didn't provide a finalAnswer. Please provide the final answer.\n`;
            }
            else {
                // Fallback: Model hallucinated a tool that doesn't exist
                context += `Observation: Tool '${response.toolName}' does not exist. Use an available tool or 'none'.\n`;
            }
        }

        return finalResult || "Error: Reached maximum iterations.";
    }

    self.addEventListener('message', async (e) => {
        const { id, type, payload } = e.data;

        if (type === MessageContext.llmResponse) {
            resolvers.get(id)?.resolve(payload);
            resolvers.delete(id);
        } else if (type === MessageContext.llmError) {
            resolvers.get(id)?.reject(new Error(payload));
            resolvers.delete(id);
        } else if (type === MessageContext.startLoop) {
            try {
                const answer = await runReActLoop(payload);
                self.postMessage({ id, type: MessageContext.agentComplete, payload: answer });
            } catch (err) {
                self.postMessage({ id, type: MessageContext.agentError, payload: err.message });
            }
        }
    });
}

The Importance of the “None” Off-Ramp

One of the most critical parts of this code is the handling of the “none” tool state. Smaller models, when presented with a JSON schema that demands a toolName, will often try to satisfy the schema even if they already know the answer (e.g., answering “What is a car?”).

By explicitly defining none: Use this if you do not need a tool, we give the model permission to bypass the tool execution block entirely. Furthermore, we must check for empty strings because JavaScript considers them falsy. Without strict string trimming and response.finalAnswer.trim() !== “” checks, the model could easily fall into an infinite fallback loop.

Step 3: The Consumer’s Implementation

Now that the generic engine is built, we can consume it. This file is the actual Web Worker script that your application will load. Here, you define the tools specific to your business domain. Because these functions run in the worker, they can perform heavy fetch calls, parse massive CSV files, or execute complex mathematics without ever blocking the UI.

import { Tool, createAgentWorker } from './prompt-chain-worker.js';

// Define custom tools
const fetchTool = new Tool(
    "FetchData",
    "Fetches text content from a URL.",
    async (url) => {
        const res = await fetch(url);
        return await res.text();
    }
);

const mathTool = new Tool(
    "Calculator",
    "Evaluates math expressions (e.g. '100 * 5').",
    (expression) => {
        return String(eval(expression));
    }
);

// Initialize the generic engine with these specific tools
createAgentWorker([fetchTool, mathTool]);

Step 4: Tying it Together in the UI

Finally, we constructed an HTML document to test our architecture. We will listen to the custom agent-log events to build a LangChain-style verbose output console, allowing the user to watch the model “think” in real-time.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Prompt API Agent Test</title>
    <link rel="stylesheet" href="./styles.css">
</head>
<body>

<h1>On-Device Agent Tester</h1>

<div class="controls">
    <input type="text" id="prompt-input" value="What is 542 multiplied by 13?" />
    <button id="run-btn">Run Agent</button>
</div>

<h3>Agent Reasoning Stream:</h3>
<div id="logs"></div>

<h3>Final Output:</h3>
<div id="result"></div>

<script type="module">
    import { PromptChainHost } from './prompt-chain-host.js';
    import {MessageContext} from "./consts.js";

    const logBox = document.getElementById('logs');
    const resultBox = document.getElementById('result');
    const runBtn = document.getElementById('run-btn');
    const input = document.getElementById('prompt-input');

    // Listen for custom events dispatched by the Host
    window.addEventListener(MessageContext.agentLog, (e) => {
        const msg = e.detail;
        let className = 'log-entry thought';
        if (msg.startsWith('Action:')) className = 'log-entry action';
        if (msg.startsWith('Observation:')) className = 'log-entry observation';

        logBox.innerHTML += `<div class="${className}">${msg}</div>`;
        logBox.scrollTop = logBox.scrollHeight;
    });

    async function init() {
        if (!window.LanguageModel) {
            resultBox.textContent = "Error: LanguageModel is not available. Please ensure Chrome flags are enabled.";
            return;
        }
        const availability = await LanguageModel.availability();
        if (availability === "unavailable") {
            resultBox.textContent = "LanguageModel API is not available on this device/browser.";
            return;
        }

        runBtn.disabled = true;
        runBtn.textContent = "Initializing Model...";

        // Instantiate the host, pointing it to the developer's custom worker
        const host = new PromptChainHost('./my-agent.js');

        await host.init(
            "You are a logical assistant. You must always output JSON matching the provided schema. Think step-by-step."
        );

        runBtn.disabled = false;
        runBtn.textContent = "Run Agent";

        runBtn.addEventListener('click', async () => {
            logBox.innerHTML = '';
            resultBox.textContent = 'Thinking...';
            runBtn.disabled = true;

            try {
                const finalAnswer = await host.runAgent(input.value);
                resultBox.textContent = finalAnswer;
            } catch (error) {
                resultBox.textContent = `Error: ${error.message}`;
            } finally {
                runBtn.disabled = false;
            }
        });
    }

    init();
</script>
</body>
</html>

Summary

By combining the power of Chrome’s native Prompt API with the asynchronous, non-blocking nature of Web Workers, we have created a highly scalable front-end architecture.

We avoided the “Framework Catholic Wedding” by keeping our core logic strictly tied to vanilla browser APIs, ensuring this code can be integrated seamlessly into React, Vue, or Web Components architectures. Furthermore, by implementing the ReAct pattern manually with strict JSON schemas, we bridged the gap between a simple chat interface and a truly autonomous, tool-wielding local agent.

The shift to on-device AI is not just a trend; it is a fundamental architectural change that reduces cloud costs and enhances user privacy. With this setup, your users can now run complex agentic workflows directly in their browser, at 60 frames per second.

If you are interested in the code, you can find it on my Github — https://github.com/gilf/prompt-chain.

Progressive Web Components: Unlocking Universal UI with Native APIs

Gil Fink — Fri, 05 Sep 2025 14:59:03 +0000

The Cross-Framework Conundrum

In the dynamic world of front-end development, we often find ourselves building intricate UI components. These components, born from hours of meticulous design and development, frequently become tethered to a specific framework — be it React, Vue, or Angular. This “framework monogamy” creates a significant challenge: how do you share that expertly crafted component across different projects, used by different teams, potentially leveraging different frameworks, without resorting to painful rewrites or clunky integration hacks?

The ideal scenario is a truly universal component: one codebase, consumable everywhere, without forcing an entire project into a specific ecosystem. This is where the power of Progressive Web Components (PWCs), built on native browser APIs, comes into play.

The Foundation: Native Web Components

At its core, a Web Component is a custom HTML element, completely defined and encapsulated by the browser’s own standards. It’s not a framework; it’s a browser feature. This means it works inherently in any modern browser and can be seamlessly integrated into any front-end framework (or no framework at all).

Let’s illustrate this with a practical example: a collapsible panel. This is a common UI element that often requires custom logic for toggling visibility, accessibility attributes, and perhaps some internal content management.

The Core Web Component: A Collapsible Panel Example

We’ll build our collapsible panel using the native Web Components API directly:

// collapsible-panel.js
class CollapsiblePanel extends HTMLElement {
  static get observedAttributes() {
    return ['open'];
  }

  constructor() {
    super();
    this.attachShadow({ mode: 'open' }); 
    this.isOpen = this.hasAttribute('open');
    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: block;
          border: 1px solid #ccc;
          margin-bottom: 10px;
        }
        .header {
          padding: 10px;
          background-color: #f0f0f0;
          cursor: pointer;
          font-weight: bold;
          display: flex;
          justify-content: space-between;
          align-items: center;
        }
        .content {
          padding: 10px;
          border-top: 1px solid #eee;
        }
        .icon {
          transition: transform 0.2s ease-in-out;
        }
        :host([open]) .icon {
          transform: rotate(90deg);
        }
      </style>
      <div class="header" role="button" tabindex="0" aria-expanded="${this.isOpen}">
        <slot name="header"></slot>
        <span class="icon">&#9658;</span>
      </div>
      <div class="content">
        <slot></slot>
      </div>
    `;
    this._header = this.shadowRoot.querySelector('.header');
    this._content = this.shadowRoot.querySelector('.content');
  }

  connectedCallback() {
    this._header.addEventListener('click', this._togglePanel);
    this._header.addEventListener('keydown', this._handleKeydown);
    this._updateContentVisibility();
  }

  disconnectedCallback() {
    this._header.removeEventListener('click', this._togglePanel);
    this._header.removeEventListener('keydown', this._handleKeydown);
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'open') {
      this.isOpen = newValue !== null;
      this._updateContentVisibility();
      this._header.setAttribute('aria-expanded', this.isOpen);
      this.dispatchEvent(new CustomEvent('panel-toggle', { detail: { open: this.isOpen } }));
    }
  }

  _togglePanel() {
    if (this.isOpen) {
      this.removeAttribute('open');
    } else {
      this.setAttribute('open', '');
    }
  };

  _handleKeydown(event) {
    if (event.key === 'Enter' || event.key === ' ') {
      event.preventDefault();
      this._togglePanel();
    }
  };

  _updateContentVisibility() {
    this._content.style.display = this.isOpen ? '' : 'none';
  }

  toggle() {
    this._togglePanel();
  }
}
customElements.define('collapsible-panel', CollapsiblePanel);

You can use this component directly in HTML:

<collapsible-panel open>
  <span slot="header">My Awesome Panel</span>
  <p>This is some content inside the collapsible panel.</p>
</collapsible-panel>
<collapsible-panel>
  <span slot="header">Another Panel</span>
  <p>More content here.</p>
</collapsible-panel>

The “Progressive” Layer: Framework Enhancements

The Web Component is fully functional on its own. However, in a framework-driven application, developers expect a more “native” integration — passing props, listening to events in a framework-idiomatic way, and potentially leveraging framework context. This is where the “progressive layer” comes in: creating lightweight, framework-specific wrappers that enhance the Web Component’s usability without adding unnecessary overhead to its core.

Enhancing for React Example

In React, we want to treat the Web Component like any other React component, managing its open state and listening to its panel-toggle event:

// CollapsiblePanelReact.jsx
import React, { useRef, useEffect, useState } from 'react';
import './collapsible-panel';

const CollapsiblePanel = ({ children, header, defaultOpen = false, onToggle }) => {
  const panelRef = useRef(null);
  const [isOpen, setIsOpen] = useState(defaultOpen);

  useEffect(() => {
    const currentPanel = panelRef.current;
    if (!currentPanel) return;
    // Synchronize React state to Web Component attribute
    if (isOpen) {
      currentPanel.setAttribute('open', '');
    } else {
      currentPanel.removeAttribute('open');
    }
    const handlePanelToggle = (event) => {
      setIsOpen(event.detail.open);
      onToggle && onToggle(event.detail.open);
    };
    currentPanel.addEventListener('panel-toggle', handlePanelToggle);
    return () => {
      currentPanel.removeEventListener('panel-toggle', handlePanelToggle);
    };
  }, [isOpen, onToggle]);

  return (
    <collapsible-panel ref={panelRef}>
      <span slot="header">{header}</span>
      {children}
    </collapsible-panel>
  );
};

export default CollapsiblePanel;

Now, a consuming developer can use it like this:

// MyApp.jsx
import React from 'react';
import CollapsiblePanel from './CollapsiblePanelReact';

const MyApp = () => {
  const handlePanelToggle = (open) => {
    console.log(`Panel is now ${open ? 'open' : 'closed'}`);
  };

  return (
    <div>
      <CollapsiblePanel header="React Specific Panel" defaultOpen onToggle={handlePanelToggle}>
        <p>This panel integrates seamlessly with React state and events.</p>
      </CollapsiblePanel>
      <button onClick={() => panelRef.current?.toggle()}>Toggle via Ref</button>
    </div>
  );
};

Enhancing for Vue Example

Vue also allows straightforward integration with Web Components. We can create a simple wrapper to align with Vue’s reactivity system and event handling:

<template>
  <collapsible-panel :open="isOpen" @panel-toggle="handleToggle">
    <template v-slot:header>{{ header }}</template>
    <slot></slot>
  </collapsible-panel>
</template>

<script>
import './collapsible-panel';
export default {
  props: {
    header: String,
    open: Boolean, 
  },
  data() {
    return {
      isOpen: this.open,
    };
  },
  watch: {
    open(newVal) {
      this.isOpen = newVal;
    }
  },
  methods: {
    handleToggle(event) {
      this.isOpen = event.detail.open;
      this.$emit('toggle', event.detail.open); 
    },
    toggle() {
      this.$refs.panel.toggle();
    }
  },
};
</script>

And in a Vue app:

<template>
  <div>
    <CollapsiblePanelVue header="Vue Specific Panel" :open="isVuePanelOpen" @toggle="handleVueToggle">
      <p>This content lives happily within a Vue component.</p>
    </CollapsiblePanelVue>
    <button @click="toggleVuePanel">Toggle Vue Panel</button>
  </div>
</template>

<script>
import CollapsiblePanelVue from './CollapsiblePanelVue.vue';
export default {
  components: {
    CollapsiblePanelVue,
  },
  data() {
    return {
      isVuePanelOpen: true,
    };
  },
  methods: {
    handleVueToggle(open) {
      this.isVuePanelOpen = open;
      console.log(`Vue panel is now ${open ? 'open' : 'closed'}`);
    },
    toggleVuePanel() {
      this.isVuePanelOpen = !this.isVuePanelOpen;
    }
  },
};
</script>

The Advantages of PWC

The Progressive Web Component pattern, leveraging native APIs, offers advantages such as:

True Interoperability: Your core UI component is truly framework-agnostic. It’s a standard browser element, guaranteeing maximum reusability across diverse tech stacks.
Reduced Development Overhead: Instead of developing and maintaining multiple versions of the same component for different frameworks, you maintain one core. The framework wrappers are thin layers, primarily focused on prop/event synchronization.
Future-Proofing: Native Web Components are part of the web platform. They are not dependent on a specific framework’s lifecycle or popularity, ensuring your components remain functional and relevant for long-term.
Flexible Integration: Teams can choose to use the native Web Component directly or opt for the framework-enhanced version, providing flexibility without sacrificing quality.

Potential Considerations and Challenges

While Progressive Web Components offer great advantages, it’s also important to acknowledge some potential considerations and challenges. Integrating Web Components into existing framework ecosystems, especially older ones, might sometimes introduce minor friction. For instance, some frameworks might require specific configurations to correctly pass complex data types (like objects or arrays) as attributes, or to handle custom events in their own idiomatic way. There’s also a learning curve for teams unfamiliar with native Web Component APIs, which can differ from framework-specific component paradigms. Furthermore, the tooling and development experience for native Web Components, while rapidly improving, might not always be as mature or feature-rich as those tailored for established frameworks. Developers might need to invest more time in setting up development servers, linting, and testing environments compared to a fully integrated framework CLI. These aspects are often manageable with careful planning and good documentation, but they are worth considering during adoption.

In today’s AI revolution, which includes AI generated code, it is easier and faster to build native Web Components and as a result these challenges become minor and less frightening.

Moving Beyond Framework Silos

In an ecosystem brimming with choices, achieving UI consistency and developer efficiency across projects can seem like an uphill battle. Progressive Web Components, built on the solid foundation of native browser APIs, offer a clear path forward. They empower us to design and build components once, knowing they can adapt and integrate smoothly into any environment. This approach allows us to transcend framework-specific silos and build a more cohesive and sustainable web experience.

Beyond the Basics: Building a Responsive Image Processing Pipeline with the Scheduler API

Gil Fink — Sun, 29 Jun 2025 07:52:50 +0000

Following up on our discussion about mastering task management in JavaScript for smoother UIs, this post will take us deeper into the practical application of the Scheduler API. We’ve seen how postTask() and yield() can combat "janky UIs" by intelligently prioritizing and breaking down operations. Now, let's explore a real-world scenario where these capabilities truly shine: creating a responsive image processing pipeline directly in the browser.

The Challenge: Client-Side Image Processing and UI Responsiveness

Client-side image processing, such as resizing, applying filters, or watermarking, can be incredibly resource-intensive. If not handled carefully, these operations can easily block the main thread, leading to frozen UIs and frustrated users. Imagine a web application where users upload and manipulate high-resolution images — without proper task management, this could quickly become a nightmare.

The Solution: Orchestrating Tasks with the Scheduler API

There are a lot of solutions in the internet that uses Web Workers for image processing task, but this time we are going to leverage the new Scheduler API. The Scheduler API provides the perfect toolkit to manage these computationally heavy tasks without sacrificing responsiveness. We can break down the image processing workflow into smaller, manageable units and assign them appropriate priorities, ensuring that user interactions always take precedence.

A Browser-Based Image Editor

Let’s consider a simplified image editor where a user can upload an image, apply a grayscale filter, and then resize it for display. Here’s how we can use the Scheduler API to keep the UI responsive throughout this process:

1. User Interaction and Immediate Feedback (User-Blocking Priority)

When a user clicks to upload an image or apply a filter, the immediate visual feedback (e.g., a loading spinner, a modal window) is essential. These tasks should be user-blocking:

async function handleImageUpload(event) {
  displayLoadingSpinner();
  await scheduler.postTask(() => {
    // Simulate a quick file read
    console.log("Image upload started: User-Blocking task");
    // ... actual file reading logic
  }, { priority: 'user-blocking' });
  // Now, transition to user-visible for processing
  processImage(event.target.files[0]);
}

2. Image Processing (User-Visible Priority)

The actual image processing (applying a filter, resizing) can be broken down. While important for the user to see the result, these operations can yield periodically to allow the UI to remain interactive. We'll use user-visible priority for these tasks:

async function processImage(file) {
  hideLoadingSpinner();
  displayProcessingIndicator();
  const image = await createImageBitmap(file);
  // Apply Grayscale Filter 
  await scheduler.postTask(async () => {
    console.log("Applying grayscale filter: User-Visible task");
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    canvas.width = image.width;
    canvas.height = image.height;
    ctx.drawImage(image, 0, 0);
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    const pixels = imageData.data;
    for (let i = 0; i < pixels.length; i += 4) {
      const avg = (pixels[i] + pixels[i + 1] + pixels[i + 2]) / 3;
      pixels[i] = avg; // Red
      pixels[i + 1] = avg; // Green
      pixels[i + 2] = avg; // Blue
      // Yield periodically to prevent UI jank
      if (i % 10000 === 0) { // Yield every 10,000 pixels (adjust as needed)
        await scheduler.yield();
        console.log("Yielded during grayscale processing");
      }
    }
    ctx.putImageData(imageData, 0, 0);
    console.log("Grayscale filter applied.");
  }, { priority: 'user-visible' });

  await scheduler.postTask(async () => {
    console.log("Resizing image: User-Visible task");
    const resizedCanvas = document.createElement('canvas');
    const resizedCtx = resizedCanvas.getContext('2d');
    const targetWidth = 400; 
    const targetHeight = (image.height / image.width) * targetWidth;
    resizedCanvas.width = targetWidth;
    resizedCanvas.height = targetHeight;
    resizedCtx.drawImage(image, 0, 0, targetWidth, targetHeight);
    console.log("Image resized.");
    displayProcessedImage(resizedCanvas.toDataURL());
  }, { priority: 'user-visible' });
  hideProcessingIndicator();
}

3. Background Operations (Background Priority)

Perhaps after processing, we want to save a smaller version of the image to local storage, or perform other non-critical operations. These can be handled with background priority:

async function cacheImage(imageDataURL) {
  await scheduler.postTask(() => {
    console.log("Caching image to local storage: Background task");
    // Simulate caching
    // localStorage.setItem('processedImage', imageDataURL);
  }, { priority: 'background' });
}

Some Considerations:

Granularity of Tasks: The key is to break down large operations into small enough chunks to allow yield() to be effective. Experiment with the if (i % 10000 === 0) condition in the grayscale example to find the optimal balance for your specific tasks.
Avoiding Over-Yielding: While yielding is good, yielding too frequently can introduce its own overhead. Find the sweet spot where the UI remains responsive without degrading overall performance.

Summary

By strategically utilizing postTask() with different priorities and judiciously employing yield() within long-running computations, we can construct highly responsive web applications, even when dealing with demanding tasks like client-side image processing. The Scheduler API empowers us to create seamless UX, ensuring that our JavaScript applications are not just functional, but truly delightful to interact with.

Task Management in JavaScript

Gil Fink — Sat, 21 Jun 2025 09:25:08 +0000

Don’t block the main thread!

As front-end developers, we’re constantly producing UI tasks. From rendering complex UI components to processing user input, and from fetching data to running animations, our applications are a built of concurrent operations. Historically, managing these tasks to ensure a smooth and responsive user experience has been a delicate balancing act, often involving a patchwork of setTimeout, requestAnimationFrame, and Promises. But what if we could tell the browser exactly how important each task is? What if we could influence when and how they run, ensuring that user-critical operations always take precedence?

Enter the Scheduler API. This evolving but powerful Web API is poised to revolutionize how we approach task management in JavaScript, offering fine-grained control over the browser’s main thread and paving the way for significantly smoother user experience.

In this post, we’ll dive deep into the Scheduler API , understand its core concepts, and explore how to leverage its capabilities to truly master task management in your front-end applications.

The Challenge: Janky UIs and Unresponsive Apps

Before we jump into the solution, let’s briefly revisit the problem. Imagine a scenario where a user clicks a button that triggers a long-running JavaScript computation. Without proper task management, this computation can block the main thread, leading to:

Janky animations: Animations stutter or freeze
Delayed input responses: User interactions such as clicks or scrolls feel unresponsive
Frozen UI: The entire page appears to hang, frustrating the user

Traditional asynchronous patterns like setTimeout(..., 0) offer a way to break up long tasks, but they don't provide any guarantees about when the continuation of your task will run relative to other browser work . This is where the Scheduler API shines.

Introducing the Scheduler API: Your Browser’s Taskmaster

The Scheduler API , accessible via scheduler (or window.scheduler in the main thread and self.scheduler in Web Workers), provides two primary functions for managing tasks:

postTask(): For scheduling new tasks with specified priorities
yield(): For yielding control of the main thread back to the browser, with the ability to prioritize the continuation of the current task

Let’s break these functions down.

scheduler.postTask(): Prioritizing New Tasks

The postTask() function allows you to add a new task to the browser's task queue with an optional priority, delay, and an AbortSignal for cancellation.

Understanding Task Priorities

The API defines three priority levels, each serving a distinct purpose:

'user-blocking' (highest priority): For tasks that are critical for immediate user interaction. Think of operations that directly respond to a user's click or keypress, where any delay would be immediately noticeable and frustrating. Examples include updating UI based on user input, or processing critical data for a new screen.
'user-visible' (default priority): For tasks that are visible to the user but not immediately blocking. Examples include loading non-critical images, updating less important UI elements, or performing background data synchronization that doesn't impact immediate user flow.
'background' (lowest priority): For tasks that are not time-critical and can run when the browser is idle. Examples include analytics reporting, pre-fetching resources for future navigation, or processing data that isn't immediately displayed.

Basic Usage of postTask()

Let’s see it in action:

// Check for feature support in the browser
if (scheduler && scheduler.postTask) {
  scheduler.postTask(() => {
    console.log("User-blocking task executed!");
    // Perform critical UI updates or calculations
  }, { priority: 'user-blocking' });

  scheduler.postTask(() => {
    console.log("User-visible task executed!");
    // Load an image, update a sidebar widget
  });

  scheduler.postTask(() => {
    console.log("Background task executed!");
    // Send analytics data, pre-fetch content
  }, { priority: 'background' });

} else {
  console.warn("Scheduler API not supported. Falling back to traditional methods.");
  // Implement fallback using setTimeout or other techniques
}

This simple example illustrates how you can declare your intentions to the browser. The browser’s scheduler will then do its best to execute these tasks according to their priority, ensuring that higher-priority tasks are given preference.

scheduler.yield(): Keeping the UI Responsive During Long Operations

While postTask() is excellent for scheduling new tasks, what about long-running operations that must execute on the main thread and can't be easily broken into entirely separate tasks? This is where scheduler.yield() comes into play.

scheduler.yield() allows you to yield control of the main thread back to the browser. It returns a Promise that resolves when the browser determines it's a good time to resume the yielded task. The crucial advantage of scheduler.yield() over setTimeout(..., 0) is that the continuation of the yielded task is often prioritized over other pending tasks of similar priority. This means your long-running operation can be chunked, allowing the browser to process user input or render updates in between chunks, leading to a much more responsive UI.

Example: Breaking Up a Long Calculation

Consider a function that performs a computationally intensive loop:

async function processLargeDataset() {
  const data = Array.from({ length: 100000 }, (_, i) => i); // Simulate large dataset
  const results = [];
  for (let i = 0; i < data.length; i++) {
    // This is an intensive calculation
    let sum = 0;
    for (let j = 0; j < 1000; j++) {
      sum += Math.sqrt(data[i] * j);
    }
    results.push(sum);
    // Yield control to the browser periodically
    if (i % 1000 === 0) { // Yield every 1000 iterations
      await scheduler.yield();
      console.log(`Yielded at iteration ${i}`);
    }
  }
  console.log("Dataset processing complete!");
  return results;
}

document.getElementById('start-btn').addEventListener('click', async () => {
  console.log("Starting large dataset processing...");
  // Show a loading indicator immediately
  document.getElementById('status').textContent = "Processing...";
  const processedData = await processLargeDataset();
  console.log("Processed data:", processedData);
  document.getElementById('status').textContent = "Done!";
});

In this example, by strategically placing await scheduler.yield(), we allow the browser to interleave its own critical work (like rendering or handling user input) with our long-running calculation. The user will experience a much smoother application, even during heavy processing.

Good Practices and Considerations

Feature Detection: Always check for scheduler before using the API, as it's still relatively new. Provide fallbacks for older browsers. There is also a good polyfill for the API here.
Don’t Over-Yield: While scheduler.yield() is powerful, don't yield too frequently. Each yield incurs a small overhead. Find a balance that keeps your UI responsive without introducing unnecessary delays.
Appropriate Priority: Carefully consider the true priority of your tasks. Overusing user-blocking can negate the benefits of the API and lead to a less responsive overall application.
Offloading Heavy Computation: For truly massive computations that don’t need direct DOM access, Web Workers remain the go-to solution. The Scheduler API complements Web Workers by managing tasks on the main thread more effectively.
Error Handling: Remember that postTask() returns a Promise, so use .then().catch() or async/await with try...catch blocks to handle potential errors or task abortions.
Progressive Enhancement: Design your applications to work without the Scheduler API first, then enhance the experience if the API is available.

Summary

The Scheduler API is a significant step forward in giving developers more control over the browser’s scheduling mechanisms. By understanding and effectively utilizing postTask() and yield() we can build more responsive, fluid, and user-friendly web applications. As this API gains wider adoption, it will undoubtedly become a cornerstone of modern front-end performance optimization.

Further reading:

Quick Tip — Using Callback Refs in React

Gil Fink — Mon, 13 Nov 2023 09:24:09 +0000

Quick Tip — Using Callback Refs in React

The Post Code in Code Sandbox

One of the usages I see a lot with useEffect in React code is to run some JavaScript code on an element reference which is stored as ref as soon as this element is mounted. For example, when an element is mounted, animate it’s content using Web Animation API.

The following code is doing exactly that:

In the code above, you set the ref to the heading element and when the component is mounted, it’s animating the heading with some premade animation.

That is easy, so why should you bother reading this post at all?

Because there is a better alternative to do exactly the same thing but without useEffect and *useRef * hooks.

The ref attribute is expecting that you will set it with one of the following types:

RefCallback<T> | RefObject<T> | null

A RefCallback is just a function that accepts the element node and returns void. In a matter of fact, whenever you use RefObject , it’s just a syntactic sugar to set the reference on the element to the current accessor of the useRef created reference. The following code is what is going to happen when you set a ref like in the first code block in this post:

<h1
  ref={(node) => {
    ref.current = node;
  }}
/>

The RefCallback function is going to run after the component is mounted, re-rendered or unmounted.

Now, packed with this knowledge, how you can refactor the above code and stop using useEffect and useRef combination?

The following code will do exactly that:

Let’s try to understand what is going on. In the code, you use the useCallback function with an empty dependency array to wrap the callback ref function. This will make sure that React runtime will run this function only on mount and that is it. No need to use the useRef or useEffect hook and you achieve the same functionality. You gain two adeed bonueses when you use callback ref. The first one is that you don’t get double rendering in development mode like you will get when you use useEffect. The second bonus is that in the case of using forwardRef and conditional rendering, the callback ref code will stay stable and work while the useEffect code might not work as expected if the element isn’t rendered due to the conditional rendering.

If you want to look at the provided code and see how it works, you can play with the previous code in this sandbox:

<a href="https://medium.com/media/9c583e21c4c620c5e9138e5c7bb3d6be/href">https://medium.com/media/9c583e21c4c620c5e9138e5c7bb3d6be/href</a>

For further reading about callback refs, you can look at React documentation: https://legacy.reactjs.org/docs/refs-and-the-dom.html#callback-refs

Integrating D3 in Qwik Apps

Gil Fink — Fri, 30 Jun 2023 17:11:41 +0000

In the past I wrote a bunch of posts that explained how to integrate D3 library and React. In this post I’ll do the same but this time I’ll show you how to integrate D3 in Qwik apps. We will build together a D3 tree and host it inside a basic Qwik app.

Are you ready?

Things to do before you start adding the suggested code:

Create a new Qwik app using the npm create qwik@latest .

Add a new route to your app, which will be used to show the D3 graph.

Creating a Qwik D3 Container Component

First you are going to add a new TreeContainer component. This component will be responsible to hold the D3 container, which will be used to create the graph.

Let’s look at the code:

The TreeContainer is going to be the div that D3 will use to create the graph. You use a signal to reference the rendered div , so you will be able to use it’s in-memory Html element representation later on.

Another thing that you can notice is the usage of useVisibileTask$. Since D3 runs only in the client, you should use the useVisibileTask$ hook that makes sure that the code which is responsible to creates the graph runs after the component’s client rendering.

Building the Graph Generator

Once the container is ready it’s time to write the createGraph function.

Here is the full function code:

Let’s analyze the code to understand what is going on. We will start in the beginning with the processSymbols function.

Sometimes we have a model that doesn’t fit into the way the D3 graphs expect their data. The processSymbols function will transform the symbols array to the needed graph representation.

At the start of the createGraph function you set the d3 tree in-memory implementation. This is happening in these lines of code:

Then, you create the tree visual representation using D3 API that creates SVG elements such as paths, circles, text and more:

The data that is being used in the example is the following symbols array:

After you wire everything you can run the app to see the following graph on your screen:

Symbol Graph

Summary

In the post I showed you how easy it is to integrate D3 in Qwik apps. The post guided you how to create the graph container and then how to create the graph by using D3 functionality.

You can take a look at the whole example in the qwik-d3-example repository.