@project-ava-supernova/core 0.2.71

package/dist/desktop/budget.js

@@ -0,0 +1,159 @@
+// ─── Desktop Automation Budget Tracker ─────────────────────────────────────
+//
+// Tracks token usage, step count, and wall-clock time during a desktop
+// automation trajectory. Enforces the three hard caps from spec 8:
+//   - Step count (default 30)
+//   - Token budget (default 500K)
+//   - Wall-clock time (default 5 minutes)
+//
+// OR'd — first-hit wins. Breach never silently continues.
+//
+// The tracker is instantiated per-trajectory and is the single source of
+// truth for the live counter displayed in the trajectory view header:
+//   "Step 7/30 · 82K / 500K tokens · 01:14"
+export const DEFAULT_BUDGET = {
+    maxSteps: 30,
+    maxTokens: 500_000,
+    maxWallMs: 5 * 60 * 1000, // 5 minutes
+};
+// ── Tracker ───────────────────────────────────────────────────────────────
+export class BudgetTracker {
+    config;
+    startedAt;
+    stepCount = 0;
+    totalTokens = 0;
+    steps = [];
+    constructor(config = {}) {
+        // Skip undefined entries so `{ maxSteps: undefined }` doesn't clobber
+        // the default. Callers sometimes pass the un-narrowed config object
+        // (e.g. from DesktopConductorConfig where maxSteps is optional).
+        const cleaned = {};
+        if (config.maxSteps !== undefined)
+            cleaned.maxSteps = config.maxSteps;
+        if (config.maxTokens !== undefined)
+            cleaned.maxTokens = config.maxTokens;
+        if (config.maxWallMs !== undefined)
+            cleaned.maxWallMs = config.maxWallMs;
+        this.config = { ...DEFAULT_BUDGET, ...cleaned };
+        this.startedAt = Date.now();
+    }
+    /** Record a completed step's token consumption. */
+    recordStep(tokens) {
+        this.stepCount += 1;
+        const stepTotal = tokens.scout + tokens.planner + tokens.actor +
+            tokens.verifier + tokens.narrator + tokens.omniParser;
+        this.totalTokens += stepTotal;
+        this.steps.push(tokens);
+        return this.snapshot();
+    }
+    /** Get the current budget state without recording a step. */
+    snapshot() {
+        const elapsedMs = Date.now() - this.startedAt;
+        let breached = false;
+        let breachReason = null;
+        if (this.stepCount >= this.config.maxSteps) {
+            breached = true;
+            breachReason = 'step_limit';
+        }
+        else if (this.totalTokens >= this.config.maxTokens) {
+            breached = true;
+            breachReason = 'token_limit';
+        }
+        else if (elapsedMs >= this.config.maxWallMs) {
+            breached = true;
+            breachReason = 'wall_clock';
+        }
+        return {
+            step: this.stepCount,
+            tokensUsed: this.totalTokens,
+            elapsedMs,
+            breached,
+            breachReason,
+            remaining: {
+                steps: Math.max(0, this.config.maxSteps - this.stepCount),
+                tokens: Math.max(0, this.config.maxTokens - this.totalTokens),
+                wallMs: Math.max(0, this.config.maxWallMs - elapsedMs),
+            },
+        };
+    }
+    /** Extend the budget (user chose "another 30 steps" at the breach prompt). */
+    extend(extra) {
+        if (extra.maxSteps)
+            this.config.maxSteps += extra.maxSteps;
+        if (extra.maxTokens)
+            this.config.maxTokens += extra.maxTokens;
+        if (extra.maxWallMs)
+            this.config.maxWallMs += extra.maxWallMs;
+    }
+    /** Format the header line for the trajectory view. */
+    formatHeader(estimatedSteps) {
+        const snap = this.snapshot();
+        const stepsLabel = estimatedSteps
+            ? `Step ${snap.step} of ~${estimatedSteps}`
+            : `Step ${snap.step}/${this.config.maxSteps}`;
+        const tokensLabel = `${formatTokenCount(snap.tokensUsed)} / ${formatTokenCount(this.config.maxTokens)} tokens`;
+        const timeLabel = formatElapsed(snap.elapsedMs);
+        return `${stepsLabel} · ${tokensLabel} · ${timeLabel}`;
+    }
+    /** Per-step breakdown for the results JSON. */
+    getStepBreakdown() {
+        return [...this.steps];
+    }
+    /** Average tokens per step — feeds the cost estimator. */
+    getAverageStepTokens() {
+        if (this.steps.length === 0)
+            return 0;
+        return Math.round(this.totalTokens / this.steps.length);
+    }
+}
+const QWEN_3_6_BLENDED_PER_TOKEN_USD = 0.000001; // ~$1/M blended I/O
+export function estimateCost(taskDescription) {
+    // Rough heuristic based on task description length and keywords.
+    // This is intentionally simple — gets replaced by learned estimates
+    // once we have trajectory data in memory.
+    const desc = taskDescription.toLowerCase();
+    const complexitySignals = [
+        'triage', 'multiple', 'three', 'several', 'all', 'each',
+        'compare', 'analyse', 'investigate', 'debug', 'fix',
+    ];
+    const simpleSignals = ['open', 'search', 'find', 'check', 'look'];
+    const complexHits = complexitySignals.filter(s => desc.includes(s)).length;
+    const simpleHits = simpleSignals.filter(s => desc.includes(s)).length;
+    if (complexHits >= 2 || desc.length > 200) {
+        return {
+            label: 'complex',
+            estimatedSteps: 28,
+            estimatedTokens: 380_000,
+            estimatedCostUsd: 380_000 * QWEN_3_6_BLENDED_PER_TOKEN_USD,
+        };
+    }
+    if (simpleHits >= 1 && complexHits === 0 && desc.length < 80) {
+        return {
+            label: 'simple',
+            estimatedSteps: 8,
+            estimatedTokens: 100_000,
+            estimatedCostUsd: 100_000 * QWEN_3_6_BLENDED_PER_TOKEN_USD,
+        };
+    }
+    return {
+        label: 'medium',
+        estimatedSteps: 20,
+        estimatedTokens: 250_000,
+        estimatedCostUsd: 250_000 * QWEN_3_6_BLENDED_PER_TOKEN_USD,
+    };
+}
+// ── Formatting helpers ────────────────────────────────────────────────────
+function formatTokenCount(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${Math.round(n / 1_000)}K`;
+    return String(n);
+}
+function formatElapsed(ms) {
+    const totalSeconds = Math.floor(ms / 1000);
+    const mins = Math.floor(totalSeconds / 60);
+    const secs = totalSeconds % 60;
+    return `${String(mins).padStart(2, '0')}:${String(secs).padStart(2, '0')}`;
+}
+//# sourceMappingURL=budget.js.map

package/dist/desktop/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/desktop/budget.ts"],"names":[],"mappings":"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"}

package/dist/desktop/capability.d.ts

@@ -0,0 +1,28 @@
+export type VisionLane = 'off' | 'local' | 'cloud-byok' | 'cloud-platform';
+export interface VisionCapability {
+    /** Can Scout offer descriptive targeting this turn (the Actor can localize)? */
+    available: boolean;
+    /** Which lane a localize() call would take. */
+    lane: VisionLane;
+    /** Is this a confirmed-good path? Local Holo + platform-hosted vision are
+     *  false until verified with H Company; cloud-BYOK (own key) is true. */
+    verified: boolean;
+    /** One-line, user-facing explanation of the current state. */
+    reason: string;
+}
+export interface VisionProbeInput {
+    /** The user's perception setting. */
+    visionMode: 'off' | 'local' | 'cloud';
+    /** The on-device model server is live (local lane ready). */
+    localModelInstalled: boolean;
+    /** The user's own H Company key is present (BYOK cloud lane). */
+    hasHCompanyKey: boolean;
+    /** A platform/account key is present (platform-hosted cloud lane). */
+    hasPlatformKey: boolean;
+    /** Optional GPU signal — future local 4B-vs-0.8B selection; does not affect
+     *  the shippable path while the local lane is unverified. */
+    hasGpu?: boolean;
+    vramMB?: number;
+}
+export declare function probeVisionCapability(i: VisionProbeInput): VisionCapability;
+//# sourceMappingURL=capability.d.ts.map

package/dist/desktop/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/desktop/capability.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAE3E,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,IAAI,EAAE,UAAU,CAAC;IACjB;6EACyE;IACzE,QAAQ,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,UAAU,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;IACtC,6DAA6D;IAC7D,mBAAmB,EAAE,OAAO,CAAC;IAC7B,iEAAiE;IACjE,cAAc,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,cAAc,EAAE,OAAO,CAAC;IACxB;iEAC6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CA4B3E"}

package/dist/desktop/capability.js

@@ -0,0 +1,39 @@
+// Vision capability probe — a pure, structured decision about whether Ava can
+// "see" a window the accessibility tree + browser can't read this turn, WHICH
+// lane would serve it, and — crucially — whether that lane is a KNOWN-GOOD one.
+//
+// Honesty is the point. The local Holo lane runs entirely on-device (private)
+// but stays `verified: false` until H Company confirms the small-model mmproj /
+// llama.cpp path + real latency — so Scout can advertise it truthfully ("local
+// vision, unverified") rather than promising quality we haven't proven. The
+// shippable, verified lane today is cloud-BYOK (the user's own H Company key).
+//
+// Pure data in / data out — no fs, no Node, safe for the sidecar to call.
+export function probeVisionCapability(i) {
+    if (i.visionMode === 'off') {
+        return {
+            available: false, lane: 'off', verified: false,
+            reason: 'Vision is off — Ava reads windows via the accessibility tree + browser only, and says so when a window is unreadable.',
+        };
+    }
+    if (i.visionMode === 'local') {
+        if (!i.localModelInstalled) {
+            return { available: false, lane: 'local', verified: false, reason: 'Local vision is selected but the on-device model is not installed yet.' };
+        }
+        // On-device + private, but UNVERIFIED until H Company confirms the small
+        // model path + latency. Surface it honestly rather than promising quality.
+        return { available: true, lane: 'local', verified: false, reason: 'Local vision (on-device, private) — unverified: quality/latency not yet confirmed.' };
+    }
+    // cloud
+    if (i.hasHCompanyKey) {
+        return { available: true, lane: 'cloud-byok', verified: true, reason: 'Vision via your own H Company key — a screenshot is sent only when a window can’t be read.' };
+    }
+    if (i.hasPlatformKey) {
+        // Platform-hosted vision is in preview until confirmed with H Company.
+        // (BYOK-only hosts pass hasPlatformKey: false — operator decision
+        // 2026-07-02 — so this lane is currently unreachable in the IDE.)
+        return { available: true, lane: 'cloud-platform', verified: false, reason: 'Vision via your Ava account (preview — for verified vision, add your own H Company key).' };
+    }
+    return { available: false, lane: 'off', verified: false, reason: 'Cloud vision needs your own H Company key (BYOK) — add it in Settings to enable it.' };
+}
+//# sourceMappingURL=capability.js.map

package/dist/desktop/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/desktop/capability.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,EAAE;AACF,0EAA0E;AA+B1E,MAAM,UAAU,qBAAqB,CAAC,CAAmB;IACvD,IAAI,CAAC,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QAC3B,OAAO;YACL,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK;YAC9C,MAAM,EAAE,uHAAuH;SAChI,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC;YAC3B,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,wEAAwE,EAAE,CAAC;QAChJ,CAAC;QACD,yEAAyE;QACzE,2EAA2E;QAC3E,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,oFAAoF,EAAE,CAAC;IAC3J,CAAC;IAED,QAAQ;IACR,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;QACrB,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,4FAA4F,EAAE,CAAC;IACvK,CAAC;IACD,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;QACrB,uEAAuE;QACvE,kEAAkE;QAClE,kEAAkE;QAClE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,0FAA0F,EAAE,CAAC;IAC1K,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,qFAAqF,EAAE,CAAC;AAC3J,CAAC"}

package/dist/desktop/conductor.d.ts

@@ -0,0 +1,104 @@
+import type { ScreenElement, ProposedAction, TrajectoryStep, Trajectory } from './types.js';
+import { type ScreenKey } from './screen-key.js';
+import { type DesktopPersonaName } from './personas.js';
+import { type PermissionLevel, type ClassificationResult } from './safety.js';
+import { type BudgetConfig, type BudgetSnapshot } from './budget.js';
+import type { UIAProvider, InputProvider, BrowserProvider, AppLauncherProvider, VisionProvider } from '../tools/desktop-providers.js';
+export interface DesktopProviders {
+    uia?: UIAProvider;
+    input?: InputProvider;
+    browser?: BrowserProvider;
+    appLauncher?: AppLauncherProvider;
+    /** Phase C3 — visual grounding fallback for windows the tree can't see. */
+    vision?: VisionProvider;
+}
+/** The host calls the LLM for a persona and returns the raw text + token counts. */
+export type PersonaModelCall = (opts: {
+    persona: DesktopPersonaName;
+    systemPrompt: string;
+    userContent: string;
+}) => Promise<{
+    text: string;
+    tokensIn: number;
+    tokensOut: number;
+}>;
+export interface ApprovalRequest {
+    action: ProposedAction;
+    classification: ClassificationResult;
+    element?: ScreenElement;
+}
+export type ApprovalFn = (req: ApprovalRequest) => Promise<boolean>;
+export type ConductorEvent = {
+    type: 'step';
+    step: TrajectoryStep;
+    budget: BudgetSnapshot;
+    header: string;
+} | {
+    type: 'narrate';
+    line: string;
+} | {
+    type: 'approval_required';
+    action: ProposedAction;
+    classification: ClassificationResult;
+} | {
+    type: 'done';
+    trajectory: Trajectory;
+} | {
+    type: 'error';
+    message: string;
+};
+export type EmitFn = (event: ConductorEvent) => void;
+export interface RunTrajectoryOptions {
+    task: string;
+    permissionLevel: PermissionLevel;
+    whitelist?: string[];
+    privilegedOptIn?: boolean;
+    budget?: Partial<BudgetConfig>;
+    providers: DesktopProviders;
+    callModel: PersonaModelCall;
+    requestApproval: ApprovalFn;
+    emit: EmitFn;
+    /** Kill switch (Ctrl+Alt+K). Checked at the top of every step. */
+    signal?: AbortSignal;
+    /**
+     * Optional diagnostic trace — one line per persona boundary (Scout saw /
+     * Planner chose / gate decided / Verifier verdict). Host routes it to its
+     * log (stderr); never user-facing. No-op if omitted.
+     */
+    log?: (line: string) => void;
+    /**
+     * Phase 3: capture a small grayscale thumbnail key of the current screen.
+     * Hosts must return null when the user's vision setting forbids capture —
+     * keying then degrades honestly to a textual app+task key. Best-effort;
+     * errors are swallowed.
+     */
+    captureScreenKey?: () => Promise<ScreenKey | null>;
+    /**
+     * Phase 3: retrieve fork-point hindsight for the current screen key —
+     * "last time this screen looked like this, X failed; Z worked." Injected
+     * into the Planner's context as TEXT; every proposed action still passes
+     * the full safety gate. Best-effort; errors are swallowed.
+     */
+    forkPointHint?: (key: ScreenKey) => Promise<string | null>;
+}
+/**
+ * Run a full desktop-automation trajectory. Returns when the task is done,
+ * the user stops it, it gets stuck, the budget is exhausted, or an error
+ * aborts it. Every step is gated, verified, and narrated.
+ */
+export declare function runDesktopTrajectory(opts: RunTrajectoryOptions): Promise<Trajectory>;
+/** Defensive: a malformed Planner output becomes a controlled 'stuck', never a crash.
+ *  Exported for the regression suite (0G) — pure function, no side effects. */
+export declare function coerceAction(parsed: Partial<ProposedAction> | null): ProposedAction;
+/**
+ * Backstop heuristic for the origin flag (Phase 1) — never the only guard.
+ * If the action's target text carries an irreversible verb that the USER'S
+ * OWN TASK never mentioned, the impetus likely came from the screen (a page
+ * saying "click Delete to continue"), whatever the Planner declared. We only
+ * ever UPGRADE user→observed, never launder observed→user.
+ * Exported for the regression suite.
+ */
+export declare function inferObservedOrigin(action: ProposedAction, task: string, elementName?: string): 'user' | 'observed' | undefined;
+/** Exported for the regression suite (0G) — pure function, no side effects. */
+export declare function parseJson<T>(text: string): T | null;
+//# sourceMappingURL=conductor.d.ts.map

package/dist/desktop/conductor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conductor.d.ts","sourceRoot":"","sources":["../../src/desktop/conductor.ts"],"names":[],"mappings":"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"}