test(cu): define provider evidence contract

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.

apps/desktop/src/main/__tests__/computer-use-real-model-policy.test.ts

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from '../computer-use-real-model-policy.js';
+
+function tool(calls: string[]): MakaTool {
+ return {
+ name: 'maka_computer',
+ description: 'test',
+ parameters: {},
+ impl: async (args) => {
+ calls.push((args as { action: string }).action);
+ return { text: 'ok' };
+ },
+ };
+}
+
+function toolSet(calls: string[]): ComputerUseToolSet {
+ return Object.assign([tool(calls)], {
+ clearSession(_sessionId: string) {},
+ sessionEvents: {
+ snapshot: () => ({ status: 'unobserved' as const, generation: 0 }),
+ physicalUserIntervened: () => ({ status: 'intervention_debounce' as const, generation: 1 }),
+ interventionDebounceElapsed: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ reobserveRequired: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ screenLocked: () => ({ status: 'screen_locked' as const, generation: 1 }),
+ screenUnlocked: () => ({ status: 'reobserve_required' as const, generation: 1 }),
+ blockedUrlDetected: () => ({ status: 'blocked_url' as const, generation: 1 }),
+ userStopped: () => ({ status: 'user_stopped' as const, generation: 1 }),
+ dynamicContentChanged: () => ({ status: 'unobserved' as const, generation: 0 }),
+ },
+ });
+}
+
+test('parses one bounded allowlist and rejects malformed policies', () => {
+ assert.deepEqual(parseComputerUseRealModelPolicy(JSON.stringify({
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ })), {
+ allowedActions: ['list_apps', 'observe', 'wait'],
+ maxTotalActions: 4,
+ });
+ assert.throws(
+ () => parseComputerUseRealModelPolicy('{"allowedActions":[],"maxTotalActions":0}'),
+ /Invalid Computer Use real-model/,
+ );
+});
+
+test('blocks disallowed and over-budget actions before dispatch', async () => {
+ const calls: string[] = [];
+ const [wrapped] = applyComputerUseRealModelPolicy(toolSet(calls), {
+ allowedActions: ['observe'],
+ maxTotalActions: 2,
+ });
+ const context = {
+ sessionId: 's',
+ turnId: 't',
+ toolCallId: 'c',
+ cwd: '/tmp',
+ abortSignal: new AbortController().signal,
+ emitOutput() {},
+ };
+
+ const allowed = await wrapped.impl({ action: 'observe' } as never, context) as { text: string };
+ assert.equal(allowed.text, 'ok');
+ const disallowed = await wrapped.impl(
+ { action: 'left_click' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ disallowed.text,
+ /unsupported_action_policy/,
+ );
+ const overBudget = await wrapped.impl(
+ { action: 'observe' } as never,
+ context,
+ ) as { text: string };
+ assert.match(
+ overBudget.text,
+ /total_action_budget_exceeded/,
+ );
+ assert.deepEqual(calls, ['observe']);
+});

apps/desktop/src/main/computer-use-host.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CuaDriverRoleSnapshot } from '@maka/computer-use';
+import type { CuaDriverBackendOptions } from '@maka/computer-use';
 import {
  selectComputerUseBackend,
  type SelectedComputerUseBackend,
@@ -44,6 +45,7 @@ export function createComputerUseHost(input: {
  mimeType: string,
  ) => { base64: string; mimeType: 'image/png' | 'image/jpeg' };
  physicalInputRecentlyActive?: () => boolean | Promise<boolean>;
+ onTrace?: CuaDriverBackendOptions['onTrace'];
  overlay?: CuOverlayHook;
 }): ComputerUseHostState {
  const manifestPath = input.manifestPath ?? (input.isPackaged
@@ -101,6 +103,7 @@ export function createComputerUseHost(input: {
  ...(input.physicalInputRecentlyActive
  ? { physicalInputRecentlyActive: input.physicalInputRecentlyActive }
  : {}),
+ ...(input.onTrace ? { onTrace: input.onTrace } : {}),
  ...(input.overlay ? { overlay: input.overlay } : {}),
  }),
  binaryPath,

apps/desktop/src/main/computer-use-real-model-policy.ts

@@ -0,0 +1,73 @@
+import type { ComputerUseToolSet, MakaTool } from '@maka/runtime';
+
+export interface ComputerUseRealModelPolicy {
+ allowedActions: readonly string[];
+ maxTotalActions: number;
+}
+
+export function parseComputerUseRealModelPolicy(
+ raw: string | undefined,
+): ComputerUseRealModelPolicy | undefined {
+ if (!raw) return undefined;
+ const value = JSON.parse(raw) as {
+ allowedActions?: unknown;
+ maxTotalActions?: unknown;
+ };
+ if (
+ !Array.isArray(value.allowedActions)
+ || value.allowedActions.length === 0
+ || value.allowedActions.some((action) =>
+ typeof action !== 'string' || !action.trim())
+ || new Set(value.allowedActions).size !== value.allowedActions.length
+ ) {
+ throw new Error('Invalid Computer Use real-model allowedActions');
+ }
+ if (
+ !Number.isInteger(value.maxTotalActions)
+ || (value.maxTotalActions as number) < 1
+ || (value.maxTotalActions as number) > 100
+ ) {
+ throw new Error('Invalid Computer Use real-model maxTotalActions');
+ }
+ return {
+ allowedActions: value.allowedActions,
+ maxTotalActions: value.maxTotalActions as number,
+ };
+}
+
+export function applyComputerUseRealModelPolicy(
+ tools: ComputerUseToolSet,
+ policy: ComputerUseRealModelPolicy | undefined,
+): ComputerUseToolSet {
+ if (!policy) return tools;
+ let totalActions = 0;
+ const allowed = new Set(policy.allowedActions);
+ const wrapped = tools.map((tool) => {
+ if (tool.name !== 'maka_computer') return tool;
+ return {
+ ...tool,
+ impl: async (args, context) => {
+ const action = typeof (args as { action?: unknown })?.action === 'string'
+ ? (args as { action: string }).action
+ : 'unknown';
+ totalActions += 1;
+ if (totalActions > policy.maxTotalActions) {
+ return {
+ text: 'maka_computer failed: total_action_budget_exceeded',
+ error: 'total_action_budget_exceeded',
+ };
+ }
+ if (!allowed.has(action)) {
+ return {
+ text: `maka_computer.${action} failed: unsupported_action_policy`,
+ error: 'unsupported_action_policy',
+ };
+ }
+ return tool.impl(args as never, context);
+ },
+ };
+ }) as ComputerUseToolSet;
+ wrapped.clearSession = (sessionId) => tools.clearSession(sessionId);
+ wrapped.sessionEvents = tools.sessionEvents;
+ return wrapped;
+}

apps/desktop/src/main/main.ts

@@ -173,6 +173,10 @@ import {
  createComputerUseHost,
 } from './computer-use-host.js';
 import { createCursorOverlayController } from './computer-use/cursor-overlay-window.js';
+import {
+ applyComputerUseRealModelPolicy,
+ parseComputerUseRealModelPolicy,
+} from './computer-use-real-model-policy.js';
 import { createComputerUseOverlayHook } from '@maka/computer-use';
 import { releaseBrowserSession } from './browser/session.js';
 import { createMainWindowController } from './main-window.js';
@@ -211,16 +215,20 @@ import { registerNotificationsIpc } from './notifications-ipc-main.js';
 // asar-packaged builds; MAKA_E2E_USER_DATA_DIR must also be set, so the fake
 // backend can't write test sessions into a real profile if someone sets only
 // MAKA_E2E.
-const isE2e =
+const hasIsolatedE2eProfile =
  !app.isPackaged &&
- process.env.MAKA_E2E === '1' &&
  !!process.env.MAKA_E2E_USER_DATA_DIR;
+const isE2e = hasIsolatedE2eProfile && process.env.MAKA_E2E === '1';
+const isComputerUseRealModelE2e =
+ hasIsolatedE2eProfile &&
+ process.env.MAKA_CU_REAL_MODEL_E2E === '1';
+const isIsolatedE2e = isE2e || isComputerUseRealModelE2e;
 
 // E2E isolation: redirect userData BEFORE the single-instance lock so the
 // lock judges the throwaway dir, not the real user data — otherwise a
 // developer with Maka open makes the E2E process exit as a "second instance".
 // Gated by isE2e (not just the dir env) so a packaged build ignores it.
-if (isE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
+if (isIsolatedE2e && process.env.MAKA_E2E_USER_DATA_DIR) {
  app.setPath('userData', process.env.MAKA_E2E_USER_DATA_DIR);
 }
 
@@ -479,7 +487,7 @@ const systemPromptService = createSystemPromptMainService({
 // BeginFrames on Linux, which stalls content-visibility inflation and any
 // frame-paced E2E protocol (measured in the scroll-geometry climb: 38 frames
 // over 31s). The E2E harness sets it, not the workflow — see fixtures.ts.
-const startHidden = (Boolean(visualSmokeFixture) || isE2e)
+const startHidden = (Boolean(visualSmokeFixture) || isIsolatedE2e)
  && process.env.MAKA_E2E_SHOW_WINDOW !== '1';
 let onMainWindowClose = (): void => {};
 const mainWindowController = createMainWindowController({
@@ -568,10 +576,31 @@ const computerUseHost = createComputerUseHost({
  }
  },
  physicalInputRecentlyActive: () => powerMonitor.getSystemIdleTime() < 1,
+ ...(isComputerUseRealModelE2e
+ ? {
+ onTrace: (event) => {
+ const tracePath = process.env.MAKA_CU_REAL_MODEL_TRACE;
+ if (!tracePath) return;
+ void import('node:fs/promises').then(({ appendFile }) =>
+ appendFile(tracePath, `${JSON.stringify(event)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ }),
+ ).catch(() => {});
+ },
+ }
+ : {}),
  overlay: createComputerUseOverlayHook(computerUseOverlay),
 });
 const computerUse = computerUseHost.selected;
-const computerUseTools = computerUse.tools;
+const computerUseTools = applyComputerUseRealModelPolicy(
+ computerUse.tools,
+ isComputerUseRealModelE2e
+ ? parseComputerUseRealModelPolicy(
+ process.env.MAKA_CU_REAL_MODEL_POLICY,
+ )
+ : undefined,
+);
 const agentTools: MakaTool[] = [buildSubagentSpawnTool(), ...buildSubagentProjectionTools()];
 const deferredTools: MakaTool[] = [
  ...riveTools,
@@ -795,6 +824,12 @@ backends.register('ai-sdk', async (ctx) => {
  const modelFetch = buildSubscriptionModelFetch(connection, ctx.sessionId, model);
  const memoryPromptSnapshot = await systemPromptService.buildLocalMemoryPromptFragment();
  const supportsVision = modelSupportsVision(connection, model);
+ const backendTools = isComputerUseRealModelE2e
+ ? computerUseTools
+ : [...(ctx.tools ?? builtinTools)];
+ const backendToolAvailability = isComputerUseRealModelE2e
+ ? { economy: false, groups: [] }
+ : toolAvailability;
 
  return new AiSdkBackend({
  sessionId: ctx.sessionId,
@@ -805,8 +840,8 @@ backends.register('ai-sdk', async (ctx) => {
  modelId: model,
  permissionEngine,
  modelFactory: (input) => getAIModel({ ...input, fetch: modelFetch }),
- tools: [...(ctx.tools ?? builtinTools)],
- toolAvailability,
+ tools: backendTools,
+ toolAvailability: backendToolAvailability,
  spawnChildAgent: (input) => runtime.spawnChildAgent(ctx.sessionId, input),
  listChildAgents: () => runtime.listChildAgents(ctx.sessionId),
  readChildAgentOutput: (input) => runtime.readChildAgentOutput(ctx.sessionId, input),
@@ -2080,7 +2115,7 @@ app.whenReady().then(async () => {
  // builds get the icon via .app bundle Info.plist; this covers the
  // dev path.
  if (process.platform === 'darwin' && app.dock) {
- if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isE2e) {
+ if (process.env.MAKA_VISUAL_SMOKE_FIXTURE || isIsolatedE2e) {
  // PR-VISUAL-SMOKE-HEADLESS: hide the dock icon so the spawned
  // Electron runs as an accessory app — no dock bounce, and it
  // never becomes frontmost / steals focus from the developer's

docs/computer-use-provider-evidence.md

@@ -0,0 +1,90 @@
+# Computer Use Provider Evidence
+
+This layer defines the evidence contract for real-model Computer Use runs. It
+does not claim that any provider has completed a real run.
+
+## Scenario Contract
+
+The scenario library defines:
+
+- an owned Electron fixture;
+- the exact user prompt and expected state;
+- forbidden effects;
+- allowed actions and per-action budgets;
+- required execution capabilities;
+- deterministic state evaluation.
+
+The fixture helper imports Electron only. It does not import Maka Runtime,
+provider transports, or execution backends.
+
+## Report Contract
+
+Reports separate three evidence classes:
+
+- `real-runtime`: a live provider model used the production Maka runtime;
+- `hermetic-protocol`: a fake transport proved protocol behavior;
+- `static-contract`: source or schema checks only.
+
+Only `real-runtime` can satisfy a provider matrix cell marked `real`.
+Policy-bypassed runs remain visibly labeled and cannot become an unqualified
+pass.
+
+The sanitizer preserves action types, timing, result codes, aggregate state,
+and allowlisted trace fields. It removes coordinates, typed text, raw UI
+content, credentials, full URLs, and provider payloads.
+
+## Next Layer
+
+A provider launcher must:
+
+1. pin a scenario from this library;
+2. run against the owned fixture and production Computer Use backend;
+3. enforce the scenario action budget before dispatch;
+4. emit a sanitized `real-runtime` report;
+5. let the provider matrix validate fixture state and forbidden effects.
+
+## First Real Run
+
+The first qualifying run completed with:
+
+- provider: OpenAI;
+- model: `gpt-5.4`;
+- evidence class: `real-runtime`;
+- tool exposure: direct E2E, with only the production `maka_computer` tool;
+- action: one app-scoped `observe`;
+- tool latency: 1117 ms;
+- total run latency: 7502 ms;
+- terminal status: `complete / end_turn`;
+- fixture oracle: verification code matched and interaction count remained zero.
+
+The direct E2E tool exposure is deliberate. The default deferred `load_tools`
+path remains a separate product contract; the launcher narrows provider
+variables while still exercising the production tool implementation, permission
+engine, Runtime, Desktop host, and cua-driver backend.
+
+During this run, OpenAI Responses tool continuation exposed a product bug:
+server-side storage generated an `item_reference` in the second request without
+a `previous_response_id`, so custom Responses endpoints rejected the tool
+result. OpenAI provider options now use `store:false`, matching the existing
+Codex subscription boundary and keeping function calls/results inline.
+
+The next run should perform one AX semantic mutation after executor hardening is
+merged.
+
+That L1 run has now completed:
+
+- scenario: `l1-single-click`;
+- provider/model: OpenAI `gpt-5.4`;
+- actions: two observations and one `click_element`;
+- no coordinate or compatibility input action was allowed;
+- semantic click latency: 1445 ms;
+- total run latency: 26023 ms;
+- fixture oracle: primary click count 1, danger click count 0, over-click count
+ 0;
+- terminal status: `complete / end_turn`;
+- result: pass.
+
+The run initially failed closed when the user's foreground ChatGPT window
+occluded the synthetic target. The fixture host now settles and raises its
+layer-0 window with `showInactive()` and `moveTop()` before declaring readiness,
+without focusing it or using an always-on-top overlay layer.