@silbercue/chrome 0.2.0

package/build/plan/plan-conditions.js

@@ -0,0 +1,242 @@
+// --- Tokenizer ---
+const OPERATORS = ["===", "!==", "==", "!=", ">=", "<=", "&&", "||", ">", "<"];
+function tokenize(expression) {
+    const tokens = [];
+    let i = 0;
+    while (i < expression.length) {
+        // Skip whitespace
+        if (/\s/.test(expression[i])) {
+            i++;
+            continue;
+        }
+        // Parentheses
+        if (expression[i] === "(") {
+            tokens.push({ type: "lparen", value: "(", raw: "(" });
+            i++;
+            continue;
+        }
+        if (expression[i] === ")") {
+            tokens.push({ type: "rparen", value: ")", raw: ")" });
+            i++;
+            continue;
+        }
+        // Operators (multi-char first)
+        let matchedOp = false;
+        for (const op of OPERATORS) {
+            if (expression.startsWith(op, i)) {
+                tokens.push({ type: "operator", value: op, raw: op });
+                i += op.length;
+                matchedOp = true;
+                break;
+            }
+        }
+        if (matchedOp)
+            continue;
+        // NOT operator (! not followed by =)
+        if (expression[i] === "!" && expression[i + 1] !== "=") {
+            tokens.push({ type: "not", value: "!", raw: "!" });
+            i++;
+            continue;
+        }
+        // Variable: $varName
+        if (expression[i] === "$") {
+            const match = expression.slice(i).match(/^\$(\w+)/);
+            if (match) {
+                tokens.push({ type: "variable", value: match[1], raw: match[0] });
+                i += match[0].length;
+                continue;
+            }
+        }
+        // String literals (single or double quoted)
+        if (expression[i] === "'" || expression[i] === '"') {
+            const quote = expression[i];
+            let str = "";
+            i++; // skip opening quote
+            while (i < expression.length && expression[i] !== quote) {
+                if (expression[i] === "\\" && i + 1 < expression.length) {
+                    str += expression[i + 1];
+                    i += 2;
+                }
+                else {
+                    str += expression[i];
+                    i++;
+                }
+            }
+            if (i >= expression.length) {
+                throw new Error(`Unterminated string literal starting at position ${i - str.length - 1}`);
+            }
+            i++; // skip closing quote
+            tokens.push({ type: "string", value: str, raw: `${quote}${str}${quote}` });
+            continue;
+        }
+        // Number literals (including negative)
+        const numMatch = expression.slice(i).match(/^-?\d+(\.\d+)?/);
+        if (numMatch) {
+            // Make sure a negative number isn't just a minus operator
+            // A negative number is valid at start, after an operator, after lparen, or after 'not'
+            const prev = tokens.length > 0 ? tokens[tokens.length - 1] : null;
+            const isNegativeNum = expression[i] === "-"
+                ? (!prev || prev.type === "operator" || prev.type === "lparen" || prev.type === "not")
+                : true;
+            if (isNegativeNum) {
+                tokens.push({ type: "number", value: Number(numMatch[0]), raw: numMatch[0] });
+                i += numMatch[0].length;
+                continue;
+            }
+        }
+        // Boolean and null keywords
+        if (expression.startsWith("true", i) && !/\w/.test(expression[i + 4] || "")) {
+            tokens.push({ type: "boolean", value: true, raw: "true" });
+            i += 4;
+            continue;
+        }
+        if (expression.startsWith("false", i) && !/\w/.test(expression[i + 5] || "")) {
+            tokens.push({ type: "boolean", value: false, raw: "false" });
+            i += 5;
+            continue;
+        }
+        if (expression.startsWith("null", i) && !/\w/.test(expression[i + 4] || "")) {
+            tokens.push({ type: "null", value: null, raw: "null" });
+            i += 4;
+            continue;
+        }
+        // Unknown character — error
+        throw new Error(`Unexpected character '${expression[i]}' at position ${i}`);
+    }
+    tokens.push({ type: "eof", value: null, raw: "" });
+    return tokens;
+}
+// --- Recursive Descent Parser ---
+class Parser {
+    tokens;
+    vars;
+    pos = 0;
+    constructor(tokens, vars) {
+        this.tokens = tokens;
+        this.vars = vars;
+    }
+    parse() {
+        const result = this.parseOr();
+        if (this.current().type !== "eof") {
+            throw new Error(`Unexpected token '${this.current().raw}' at end of expression`);
+        }
+        return result;
+    }
+    current() {
+        return this.tokens[this.pos];
+    }
+    advance() {
+        const token = this.tokens[this.pos];
+        this.pos++;
+        return token;
+    }
+    parseOr() {
+        let left = this.parseAnd();
+        while (this.current().type === "operator" && this.current().value === "||") {
+            this.advance();
+            const right = this.parseAnd();
+            left = left || right;
+        }
+        return left;
+    }
+    parseAnd() {
+        let left = this.parseComparison();
+        while (this.current().type === "operator" && this.current().value === "&&") {
+            this.advance();
+            const right = this.parseComparison();
+            left = left && right;
+        }
+        return left;
+    }
+    parseComparison() {
+        let left = this.parseUnary();
+        const compOps = ["===", "==", "!==", "!=", ">", "<", ">=", "<="];
+        while (this.current().type === "operator" && compOps.includes(this.current().value)) {
+            const op = this.advance().value;
+            const right = this.parseUnary();
+            left = this.applyComparison(left, op, right);
+        }
+        return left;
+    }
+    parseUnary() {
+        if (this.current().type === "not") {
+            this.advance();
+            const operand = this.parseUnary();
+            return !operand;
+        }
+        return this.parsePrimary();
+    }
+    parsePrimary() {
+        const token = this.current();
+        if (token.type === "lparen") {
+            this.advance(); // skip (
+            const value = this.parseOr();
+            if (this.current().type !== "rparen") {
+                throw new Error("Expected closing parenthesis");
+            }
+            this.advance(); // skip )
+            return value;
+        }
+        if (token.type === "variable") {
+            this.advance();
+            const varName = token.value;
+            return varName in this.vars ? this.vars[varName] : undefined;
+        }
+        if (token.type === "string") {
+            this.advance();
+            return token.value;
+        }
+        if (token.type === "number") {
+            this.advance();
+            return token.value;
+        }
+        if (token.type === "boolean") {
+            this.advance();
+            return token.value;
+        }
+        if (token.type === "null") {
+            this.advance();
+            return null;
+        }
+        throw new Error(`Unexpected token '${token.raw}'`);
+    }
+    applyComparison(left, op, right) {
+        switch (op) {
+            case "===": return left === right;
+            case "==": return left == right;
+            case "!==": return left !== right;
+            case "!=": return left != right;
+            case ">": return left > right;
+            case "<": return left < right;
+            case ">=": return left >= right;
+            case "<=": return left <= right;
+            default: return false;
+        }
+    }
+}
+/**
+ * Evaluate a simple condition expression against the vars map.
+ * Supports: ==, ===, !=, !==, >, <, >=, <=, &&, ||, !
+ * Variables via $varName syntax.
+ * String literals via single or double quotes.
+ * Number literals, boolean literals (true/false), null.
+ *
+ * SECURITY: No dynamic code evaluation. Parser-based.
+ * Unknown variables evaluate to undefined.
+ */
+export function evaluateCondition(expression, vars) {
+    // Empty expression → true (step executes)
+    if (!expression || expression.trim() === "") {
+        return true;
+    }
+    try {
+        const tokens = tokenize(expression.trim());
+        const parser = new Parser(tokens, vars);
+        const result = parser.parse();
+        return !!result;
+    }
+    catch (err) {
+        console.error(`[plan-conditions] Invalid expression: "${expression}" — ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}

package/build/plan/plan-executor.d.ts

@@ -0,0 +1,49 @@
+import type { ToolRegistry } from "../registry.js";
+import type { ToolResponse, ToolMeta } from "../types.js";
+import type { VarsMap } from "./plan-variables.js";
+import type { PlanStateStore } from "./plan-state-store.js";
+export type ErrorStrategy = "abort" | "continue" | "screenshot";
+export interface SuspendConfig {
+    /** Frage an den Agent */
+    question?: string;
+    /** Context-Typ: "screenshot" erzeugt automatisch einen Screenshot */
+    context?: "screenshot";
+    /** Bedingung: Plan pausiert NACH Step-Ausfuehrung wenn Bedingung true */
+    condition?: string;
+}
+export interface PlanStep {
+    tool: string;
+    params?: Record<string, unknown>;
+    saveAs?: string;
+    if?: string;
+    suspend?: SuspendConfig;
+}
+export interface StepResult {
+    step: number;
+    tool: string;
+    result: ToolResponse;
+    skipped?: boolean;
+    condition?: string;
+}
+export interface PlanOptions {
+    vars?: VarsMap;
+    errorStrategy?: ErrorStrategy;
+    /** Fuer Resume: der gespeicherte Plan-State */
+    resumeState?: {
+        suspendedAtIndex: number;
+        completedResults: StepResult[];
+        vars: VarsMap;
+        answer: string;
+    };
+}
+export interface SuspendedPlanResponse {
+    status: "suspended";
+    planId: string;
+    question: string;
+    completedSteps: StepResult[];
+    screenshot?: string;
+    _meta?: ToolMeta;
+}
+/** executePlan kann jetzt entweder ToolResponse oder SuspendedPlanResponse zurueckgeben */
+export type PlanExecutionResult = ToolResponse | SuspendedPlanResponse;
+export declare function executePlan(steps: PlanStep[], registry: ToolRegistry, options?: PlanOptions, stateStore?: PlanStateStore): Promise<PlanExecutionResult>;

package/build/plan/plan-executor.js

@@ -0,0 +1,259 @@
+import { substituteVars, extractResultValue } from "./plan-variables.js";
+import { evaluateCondition } from "./plan-conditions.js";
+const DEFAULT_SUSPEND_QUESTION = "Plan pausiert -- Bedingung erfuellt. Wie fortfahren?";
+export async function executePlan(steps, registry, options, stateStore) {
+    const start = performance.now();
+    let results = [];
+    const vars = { ...(options?.vars ?? {}) };
+    const errorStrategy = options?.errorStrategy ?? "abort";
+    let startIndex = 0;
+    let isResumeFirstStep = false;
+    // --- Resume: restore state from previous suspend ---
+    if (options?.resumeState) {
+        const rs = options.resumeState;
+        Object.assign(vars, rs.vars);
+        vars["answer"] = rs.answer;
+        results = [...rs.completedResults];
+        startIndex = rs.suspendedAtIndex;
+        isResumeFirstStep = true;
+    }
+    for (let i = startIndex; i < steps.length; i++) {
+        const step = steps[i];
+        // --- Conditional: evaluate if clause ---
+        if (step.if !== undefined && step.if !== "") {
+            const conditionResult = evaluateCondition(step.if, vars);
+            if (!conditionResult) {
+                results.push({
+                    step: i + 1,
+                    tool: step.tool,
+                    result: {
+                        content: [{ type: "text", text: `Skipped: condition "${step.if}" was false` }],
+                        _meta: { elapsedMs: 0, method: step.tool },
+                    },
+                    skipped: true,
+                    condition: step.if,
+                });
+                continue;
+            }
+        }
+        // --- Pre-Suspend (without condition): pause BEFORE step execution ---
+        // Skip pre-suspend on the first step of a resume (agent already answered)
+        if (step.suspend && !step.suspend.condition && !isResumeFirstStep) {
+            if (!stateStore) {
+                console.warn("[plan-executor] suspend config on step but no stateStore provided — ignoring suspend");
+            }
+            else {
+                const question = step.suspend.question ?? DEFAULT_SUSPEND_QUESTION;
+                let screenshot;
+                if (step.suspend.context === "screenshot") {
+                    try {
+                        const ssResult = await registry.executeTool("screenshot", {});
+                        if (!ssResult.isError) {
+                            for (const block of ssResult.content) {
+                                if (block.type === "image") {
+                                    screenshot = block.data;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Screenshot is best-effort
+                    }
+                }
+                const planId = stateStore.suspend({
+                    steps,
+                    suspendedAtIndex: i,
+                    vars: { ...vars },
+                    errorStrategy,
+                    completedResults: [...results],
+                    question,
+                });
+                return {
+                    status: "suspended",
+                    planId,
+                    question,
+                    completedSteps: [...results],
+                    screenshot,
+                    _meta: {
+                        elapsedMs: Math.round(performance.now() - start),
+                        method: "run_plan",
+                    },
+                };
+            }
+        }
+        // Reset resume-first-step flag after pre-suspend check
+        isResumeFirstStep = false;
+        // --- Variable substitution ---
+        const resolvedParams = step.params
+            ? substituteVars(step.params, vars)
+            : {};
+        // --- Execute step ---
+        let stepResult;
+        try {
+            stepResult = await registry.executeTool(step.tool, resolvedParams);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            stepResult = {
+                content: [{ type: "text", text: `Exception in ${step.tool}: ${message}` }],
+                isError: true,
+                _meta: { elapsedMs: 0, method: step.tool },
+            };
+        }
+        // --- saveAs: store result as variable ---
+        if (!stepResult.isError && step.saveAs) {
+            vars[step.saveAs] = extractResultValue(stepResult);
+        }
+        results.push({ step: i + 1, tool: step.tool, result: stepResult });
+        // --- Post-Suspend (with condition): pause AFTER step execution if condition is true ---
+        if (step.suspend?.condition && !stepResult.isError) {
+            const suspendConditionResult = evaluateCondition(step.suspend.condition, vars);
+            if (suspendConditionResult) {
+                if (!stateStore) {
+                    console.warn("[plan-executor] suspend condition met but no stateStore provided — ignoring suspend");
+                }
+                else {
+                    const question = step.suspend.question ?? DEFAULT_SUSPEND_QUESTION;
+                    let screenshot;
+                    if (step.suspend.context === "screenshot") {
+                        try {
+                            const ssResult = await registry.executeTool("screenshot", {});
+                            if (!ssResult.isError) {
+                                for (const block of ssResult.content) {
+                                    if (block.type === "image") {
+                                        screenshot = block.data;
+                                        break;
+                                    }
+                                }
+                            }
+                        }
+                        catch {
+                            // Screenshot is best-effort
+                        }
+                    }
+                    const planId = stateStore.suspend({
+                        steps,
+                        suspendedAtIndex: i + 1,
+                        vars: { ...vars },
+                        errorStrategy,
+                        completedResults: [...results],
+                        question,
+                    });
+                    return {
+                        status: "suspended",
+                        planId,
+                        question,
+                        completedSteps: [...results],
+                        screenshot,
+                        _meta: {
+                            elapsedMs: Math.round(performance.now() - start),
+                            method: "run_plan",
+                        },
+                    };
+                }
+            }
+        }
+        // --- Error handling based on strategy ---
+        if (stepResult.isError) {
+            if (errorStrategy === "abort") {
+                return buildPlanResponse(results, steps.length, start, true, errorStrategy);
+            }
+            if (errorStrategy === "screenshot") {
+                // Take screenshot and append to the failed step
+                try {
+                    const screenshotResult = await registry.executeTool("screenshot", {});
+                    // Append screenshot content to the failed step's result
+                    const lastResult = results[results.length - 1];
+                    if (!screenshotResult.isError) {
+                        for (const block of screenshotResult.content) {
+                            if (block.type === "image") {
+                                lastResult.result = {
+                                    ...lastResult.result,
+                                    content: [...lastResult.result.content, block],
+                                };
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Screenshot is best-effort
+                }
+                return buildPlanResponse(results, steps.length, start, true, errorStrategy);
+            }
+            // errorStrategy === "continue": just keep going
+        }
+    }
+    return buildPlanResponse(results, steps.length, start, false, errorStrategy);
+}
+function buildPlanResponse(results, stepsTotal, startTime, aborted, errorStrategy = "abort") {
+    const elapsedMs = Math.round(performance.now() - startTime);
+    const contentBlocks = [];
+    let okCount = 0;
+    let failCount = 0;
+    let skipCount = 0;
+    for (const r of results) {
+        if (r.skipped) {
+            skipCount++;
+            contentBlocks.push({
+                type: "text",
+                text: `[${r.step}/${stepsTotal}] SKIP ${r.tool} (condition: ${r.condition})`,
+            });
+            continue;
+        }
+        const status = r.result.isError ? "FAIL" : "OK";
+        if (r.result.isError)
+            failCount++;
+        else
+            okCount++;
+        const stepMs = r.result._meta?.elapsedMs ?? 0;
+        // Build step header text from text content blocks
+        const textParts = r.result.content
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+        contentBlocks.push({
+            type: "text",
+            text: `[${r.step}/${stepsTotal}] ${status} ${r.tool} (${stepMs}ms): ${textParts}`,
+        });
+        // Preserve non-text content blocks (e.g. screenshot images)
+        for (const block of r.result.content) {
+            if (block.type !== "text") {
+                contentBlocks.push(block);
+            }
+        }
+    }
+    if (aborted) {
+        contentBlocks.push({
+            type: "text",
+            text: `\nPlan aborted at step ${results.length}/${stepsTotal}`,
+        });
+    }
+    // Summary for continue strategy with errors
+    if (errorStrategy === "continue" && failCount > 0 && !aborted) {
+        const parts = [`${okCount}/${stepsTotal} OK`, `${failCount} FAIL`];
+        if (skipCount > 0)
+            parts.push(`${skipCount} SKIP`);
+        contentBlocks.push({
+            type: "text",
+            text: `\nPlan completed with errors: ${parts.join(", ")}`,
+        });
+    }
+    // Determine isError:
+    // - abort/screenshot: aborted flag
+    // - continue: only if ALL executed (non-skipped) steps failed
+    const executedCount = okCount + failCount;
+    const isError = errorStrategy === "continue" && !aborted
+        ? executedCount > 0 && failCount === executedCount
+        : aborted;
+    return {
+        content: contentBlocks,
+        isError: isError || undefined,
+        _meta: {
+            elapsedMs,
+            method: "run_plan",
+            stepsTotal,
+            stepsCompleted: okCount,
+        },
+    };
+}

package/build/plan/plan-state-store.d.ts

@@ -0,0 +1,24 @@
+import type { PlanStep, StepResult, ErrorStrategy } from "./plan-executor.js";
+import type { VarsMap } from "./plan-variables.js";
+export interface SuspendedPlanState {
+    planId: string;
+    steps: PlanStep[];
+    /** Index des Steps an dem der Plan pausiert wurde (naechster auszufuehrender Step) */
+    suspendedAtIndex: number;
+    vars: VarsMap;
+    errorStrategy: ErrorStrategy;
+    completedResults: StepResult[];
+    question: string;
+    createdAt: number;
+}
+export declare class PlanStateStore {
+    private store;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    /** Suspend speichert den Plan-State und gibt eine planId zurueck */
+    suspend(state: Omit<SuspendedPlanState, "planId" | "createdAt">): string;
+    /** Resume laedt und entfernt den Plan-State. Gibt null zurueck wenn abgelaufen oder nicht gefunden. */
+    resume(planId: string): SuspendedPlanState | null;
+    /** Bereinigt abgelaufene Eintraege (aufgerufen bei suspend) */
+    private cleanup;
+}

package/build/plan/plan-state-store.js

@@ -0,0 +1,43 @@
+import { randomUUID } from "node:crypto";
+export class PlanStateStore {
+    store = new Map();
+    ttlMs;
+    constructor(ttlMs = 5 * 60 * 1000) {
+        this.ttlMs = ttlMs;
+    }
+    /** Suspend speichert den Plan-State und gibt eine planId zurueck */
+    suspend(state) {
+        this.cleanup();
+        const planId = randomUUID();
+        this.store.set(planId, {
+            ...state,
+            planId,
+            createdAt: Date.now(),
+        });
+        return planId;
+    }
+    /** Resume laedt und entfernt den Plan-State. Gibt null zurueck wenn abgelaufen oder nicht gefunden. */
+    resume(planId) {
+        this.cleanup();
+        const state = this.store.get(planId);
+        if (!state) {
+            return null;
+        }
+        // TTL check (>= so that TTL=0 expires immediately)
+        if (Date.now() - state.createdAt >= this.ttlMs) {
+            this.store.delete(planId);
+            return null;
+        }
+        this.store.delete(planId);
+        return state;
+    }
+    /** Bereinigt abgelaufene Eintraege (aufgerufen bei suspend) */
+    cleanup() {
+        const now = Date.now();
+        for (const [id, state] of this.store) {
+            if (now - state.createdAt >= this.ttlMs) {
+                this.store.delete(id);
+            }
+        }
+    }
+}

package/build/plan/plan-variables.d.ts

@@ -0,0 +1,16 @@
+import type { ToolResponse } from "../types.js";
+export type VarsMap = Record<string, unknown>;
+/**
+ * Substitute $var references in a params object.
+ * Replaces string values matching "$varName" pattern with the value from vars.
+ * Supports nested objects and arrays.
+ * Unresolved $var references remain as-is (no error — the tool will handle invalid params).
+ */
+export declare function substituteVars(params: Record<string, unknown>, vars: VarsMap): Record<string, unknown>;
+/**
+ * Extract the text content from a ToolResponse for saveAs.
+ * Concatenates all text content blocks into a single string.
+ * If the text is valid JSON, parse it and return the parsed value.
+ * Otherwise return the raw text string.
+ */
+export declare function extractResultValue(result: ToolResponse): unknown;