@easonwumac/computer-linker 0.1.2

package/dist/computer-contract.d.ts

@@ -0,0 +1,33 @@
+import type { AuditEventInput } from "./audit.js";
+import { type ComputerOperationEnvelope } from "./computer-operation-registry.js";
+import { type TunnelProcessSnapshot } from "./tunnels.js";
+import { type WorkspaceOperationInput } from "./workspace-operations.js";
+export interface McpClientSetupOptions {
+    tunnels?: TunnelProcessSnapshot[];
+    includeSecrets?: boolean;
+}
+export type ComputerOperationErrorCode = "invalid_request" | "unknown_scope" | "unknown_operation" | "permission_denied" | "path_out_of_scope" | "unsupported_platform" | "provider_unavailable" | "timeout" | "process_not_found" | "os_permission_required" | "execution_failed";
+export interface ComputerOperationError {
+    code: ComputerOperationErrorCode;
+    message: string;
+    retryable: boolean;
+    details: Record<string, unknown>;
+}
+export interface ComputerOperationResult<T = unknown> {
+    ok: boolean;
+    operationId: string;
+    scope: string;
+    op: string;
+    startedAt: string;
+    durationMs: number;
+    data?: T;
+    error?: ComputerOperationError;
+    warnings: string[];
+}
+export declare function getComputerInfo(): unknown;
+export declare function getMcpClientSetup(options?: McpClientSetupOptions): unknown;
+export declare function runComputerOperation(envelope: ComputerOperationEnvelope): Promise<ComputerOperationResult>;
+export declare function getOperationHistory(input: Record<string, unknown>): unknown;
+export declare function normalizeComputerOperationInput(envelope: ComputerOperationEnvelope, workspaceOperation?: string): WorkspaceOperationInput;
+export declare function computerOperationAuditFields(envelope: ComputerOperationEnvelope): Promise<Partial<AuditEventInput>>;
+export declare function computerOperationName(op: string): string;

package/dist/computer-contract.js

@@ -0,0 +1,384 @@
+import { randomUUID } from "node:crypto";
+import { platform, release, arch, type } from "node:os";
+import { basename } from "node:path";
+import { readAuditEvents } from "./audit.js";
+import { getLocalPortCapabilities } from "./capabilities.js";
+import { workspaceCapabilityPolicy } from "./capability-policy.js";
+import { computerOperationContract, computerOperationMap, publicComputerOperationRegistry, } from "./computer-operation-registry.js";
+import { loadConfig } from "./config.js";
+import { historyInsight } from "./history-insights.js";
+import { compatibilityMcpTools, exposedMcpTools, genericMcpTools, mcpToolSurface } from "./mcp-surface.js";
+import { workspaceLinkerVersion } from "./package-metadata.js";
+import { PermissionDeniedError } from "./permissions.js";
+import { connectionProfile } from "./profile.js";
+import { screenshotCapability } from "./screenshot.js";
+import { listTunnelProcesses } from "./tunnels.js";
+import { WorkspaceRegistry } from "./workspaces.js";
+import { allowedWorkspaceOperations, normalizeWorkspaceOperationInput, runWorkspaceOperation, workspaceOperationAuditFields, } from "./workspace-operations.js";
+const historyViewMap = {
+    "history.last": "last",
+    "history.timeline": "timeline",
+    "history.sessions": "sessions",
+    "history.connections": "connections",
+    "history.failed_replay": "failed_replay",
+    "history.debug_bundle": "debug_bundle",
+};
+const genericAgentInstructions = [
+    "You are connected to Computer Linker, a local MCP server for this computer.",
+    "First call get_computer_info to inspect available scopes, permissions, and safety boundaries.",
+    "Call computer_operation with dotted ops from computerOperationRegistry and the stable envelope {scope, op, target, input, options}.",
+    "Stay inside configured scopes. Prefer file.search, file.read, code.context, and get_operation_history before write.",
+    "Use write, shell, command, or codex operations only when the reported permissions allow them.",
+    "Do not call workspace_operation, read, ls, grep, glob, or create_file unless the server explicitly exposes compatibility tools.",
+    "If tunnel or connection behavior is unclear, inspect get_operation_history before changing anything.",
+];
+export function getComputerInfo() {
+    const config = loadConfig();
+    const registry = new WorkspaceRegistry(config);
+    const capabilities = getLocalPortCapabilities();
+    const activeMcpToolSurface = mcpToolSurface();
+    return {
+        kind: "computer-linker-computer-info",
+        schemaVersion: 1,
+        machineId: config.machineId,
+        machineName: config.machineName,
+        platform: {
+            os: platform(),
+            name: type(),
+            arch: arch(),
+            release: release(),
+            shell: process.env.SHELL ? basename(process.env.SHELL) : undefined,
+            nodeVersion: process.version,
+        },
+        service: {
+            name: "computer-linker",
+            version: workspaceLinkerVersion(),
+            transports: ["stdio", "http"],
+            localUrl: capabilities.startup?.localMcpUrl ?? `http://${config.host ?? "127.0.0.1"}:${config.port ?? 3939}/mcp`,
+            publicUrl: capabilities.exposure?.publicMcpUrl ?? null,
+        },
+        scopes: registry.listDefinedWorkspaces().map((workspace) => ({
+            id: workspace.id,
+            name: workspace.name,
+            type: "folder",
+            roots: [workspace.path],
+            permissions: workspace.permissions,
+            policy: workspace.policy ?? {},
+            capabilityPolicy: workspaceCapabilityPolicy(workspace.permissions),
+            allowedOperations: allowedWorkspaceOperations(workspace.permissions),
+        })),
+        tools: {
+            ...(capabilities.toolReadiness && typeof capabilities.toolReadiness === "object" ? capabilities.toolReadiness : {}),
+            screenshot: screenshotCapability(),
+        },
+        operationContract: computerOperationContract,
+        operationRegistry: publicComputerOperationRegistry(),
+        compatibilityOperationRegistry: capabilities.operationRegistry,
+        mcpToolSurface: {
+            active: activeMcpToolSurface,
+            exposedTools: exposedMcpTools(activeMcpToolSurface),
+            compatibilityOptIn: "COMPUTER_LINKER_MCP_TOOL_SURFACE=compatibility",
+        },
+        compatibility: {
+            workspaceTools: [...compatibilityMcpTools],
+            genericTools: [...genericMcpTools],
+        },
+        status: {
+            ready: true,
+            blockingReasons: [],
+            warnings: [],
+        },
+    };
+}
+export function getMcpClientSetup(options = {}) {
+    const config = loadConfig();
+    const profile = connectionProfile(config, options.includeSecrets === true);
+    const tunnelSnapshots = options.tunnels ?? listTunnelProcesses();
+    const activeOpenAiTunnel = runningOpenAiTunnel(tunnelSnapshots);
+    const activeOpenAiTunnelId = activeOpenAiTunnel ? openAiTunnelIdFromSnapshot(activeOpenAiTunnel) : undefined;
+    const detectedPublicUrl = runningTunnelPublicUrl(tunnelSnapshots);
+    const publicBaseUrl = detectedPublicUrl ?? config.publicBaseUrl;
+    const publicMcpUrl = publicBaseUrl ? new URL("/mcp", publicBaseUrl).href : null;
+    const publicBaseUrlSource = detectedPublicUrl
+        ? "running-tunnel"
+        : config.publicBaseUrl ? "configured" : null;
+    const remoteReady = Boolean((activeOpenAiTunnel || publicMcpUrl?.startsWith("https://")) && config.ownerToken);
+    const blockingReasons = [];
+    const remoteBlockingReasons = [
+        ...(!config.ownerToken ? ["ownerToken is required before exposing HTTP MCP beyond loopback"] : []),
+        ...(!activeOpenAiTunnel && !publicMcpUrl ? ["No public MCP URL is configured or detected"] : []),
+        ...(!activeOpenAiTunnel && publicMcpUrl && !publicMcpUrl.startsWith("https://") ? ["public MCP URL must use https:// for remote clients"] : []),
+    ];
+    const warnings = [
+        ...(!activeOpenAiTunnel && !publicMcpUrl ? ["No public MCP URL is configured or detected; local stdio/loopback clients can still connect."] : []),
+        ...(detectedPublicUrl && detectedPublicUrl !== config.publicBaseUrl ? ["Detected tunnel URL is temporary until saved as publicBaseUrl."] : []),
+    ];
+    const localBearerHeader = config.ownerToken ? profile.http.auth.header ?? "Authorization: Bearer <ownerToken>" : null;
+    return {
+        kind: "computer-linker-mcp-client-setup",
+        schemaVersion: 1,
+        machineId: config.machineId,
+        machineName: config.machineName,
+        localReady: true,
+        ready: true,
+        remoteReady,
+        connection: {
+            stdio: profile.stdio,
+            localMcpUrl: profile.http.localMcpUrl,
+            publicMcpUrl,
+            publicBaseUrl: publicBaseUrl ?? null,
+            publicBaseUrlSource,
+            tunnel: activeOpenAiTunnel
+                ? {
+                    provider: "openai",
+                    mode: "secure-mcp-tunnel",
+                    status: "running",
+                    tunnelId: activeOpenAiTunnelId ?? activeOpenAiTunnel.id,
+                    localMcpTarget: profile.http.localMcpUrl,
+                    publicUrlRequired: false,
+                }
+                : null,
+        },
+        auth: {
+            mode: activeOpenAiTunnel ? "openai-secure-tunnel" : config.ownerToken ? "owner-token-or-oauth" : "loopback-only",
+            bearerHeader: activeOpenAiTunnel ? null : localBearerHeader,
+            alternateBearerHeader: config.ownerToken
+                ? activeOpenAiTunnel
+                    ? null
+                    : options.includeSecrets === true
+                        ? `x-computer-linker-token: ${config.ownerToken}`
+                        : "x-computer-linker-token: <ownerToken>"
+                : null,
+            localBearerHeader,
+            oauthDiscovery: publicMcpUrl && config.ownerToken && config.publicBaseUrl
+                ? {
+                    authorizationServerMetadataUrl: new URL("/.well-known/oauth-authorization-server", config.publicBaseUrl).href,
+                    protectedResourceMetadataUrl: new URL("/.well-known/oauth-protected-resource/mcp", config.publicBaseUrl).href,
+                    scopes: ["computer-linker"],
+                }
+                : null,
+            notes: activeOpenAiTunnel
+                ? ["OpenAI tunnel-client forwards the owner token to the private local MCP server; do not paste a bearer token into ChatGPT Tunnel mode."]
+                : [],
+        },
+        tools: [...genericMcpTools],
+        operationShape: {
+            tool: "computer_operation",
+            contract: computerOperationContract,
+            registry: publicComputerOperationRegistry(),
+            envelope: {
+                scope: "app",
+                op: "file.read",
+                target: "README.md",
+                input: {},
+                options: { maxBytes: 65536 },
+            },
+        },
+        firstPrompt: "Call get_computer_info, choose an allowed scope, then use computer_operation with dotted ops from computerOperationRegistry and the stable scope/op/target/input/options envelope. Use get_operation_history to inspect what happened. Do not call compatibility workspace tools unless the server explicitly exposes them.",
+        agentInstructions: genericAgentInstructions,
+        blockingReasons,
+        remoteBlockingReasons,
+        warnings,
+        nextActions: mcpClientSetupNextActions(remoteReady, remoteBlockingReasons, warnings, activeOpenAiTunnelId),
+    };
+}
+export async function runComputerOperation(envelope) {
+    const operationId = `op_${randomUUID()}`;
+    const startedAt = new Date();
+    const started = performance.now();
+    const inputScope = optionalString(envelope.scope) ?? "";
+    const inputOp = optionalString(envelope.op) ?? "";
+    try {
+        const scope = stringValue(envelope.scope, "scope");
+        const op = stringValue(envelope.op, "op");
+        const workspaceOperation = computerOperationMap[op] ?? op;
+        const input = normalizeComputerOperationInput(envelope, workspaceOperation);
+        const registry = new WorkspaceRegistry(loadConfig());
+        const workspace = await registry.openWorkspace(scope);
+        return {
+            ok: true,
+            operationId,
+            scope,
+            op,
+            startedAt: startedAt.toISOString(),
+            durationMs: elapsedMs(started),
+            data: await runWorkspaceOperation(registry, workspace, input),
+            warnings: [],
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            operationId,
+            scope: inputScope,
+            op: inputOp,
+            startedAt: startedAt.toISOString(),
+            durationMs: elapsedMs(started),
+            error: computerOperationError(error),
+            warnings: [],
+        };
+    }
+}
+export function getOperationHistory(input) {
+    const view = optionalString(input.view) ?? "last";
+    const scope = optionalString(input.scope ?? input.workspace ?? input.workspaceId);
+    if (view === "raw") {
+        return {
+            events: readAuditEvents({
+                workspaceId: scope,
+                query: optionalString(input.q ?? input.query),
+                limit: optionalPositiveInteger(input.limit),
+            }),
+        };
+    }
+    return historyInsight({
+        view,
+        workspaceId: scope,
+        query: optionalString(input.q ?? input.query),
+        limit: optionalPositiveInteger(input.limit),
+    });
+}
+export function normalizeComputerOperationInput(envelope, workspaceOperation = stringValue(envelope.op, "op")) {
+    const sourceOp = stringValue(envelope.op, "op");
+    const mappedInput = {
+        ...(envelope.input ?? {}),
+        ...historyViewInput(sourceOp),
+    };
+    return normalizeWorkspaceOperationInput({
+        operation: workspaceOperation,
+        target: envelope.target,
+        input: mappedInput,
+        options: envelope.options ?? {},
+    });
+}
+export async function computerOperationAuditFields(envelope) {
+    const scope = optionalString(envelope.scope);
+    const op = optionalString(envelope.op);
+    let workspaceOperationInput;
+    try {
+        workspaceOperationInput = op ? normalizeComputerOperationInput(envelope, computerOperationMap[op] ?? op) : undefined;
+    }
+    catch {
+        workspaceOperationInput = undefined;
+    }
+    const fields = {
+        workspaceRef: scope,
+        operation: op,
+        target: optionalString(envelope.target),
+        ...(workspaceOperationInput ? workspaceOperationAuditFields(workspaceOperationInput) : {}),
+    };
+    fields.operation = op ?? fields.operation;
+    fields.target = optionalString(envelope.target) ?? fields.target;
+    if (!scope)
+        return fields;
+    try {
+        const registry = new WorkspaceRegistry(loadConfig());
+        const workspace = await registry.openWorkspace(scope);
+        return {
+            ...fields,
+            workspaceId: workspace.exposedPath.id,
+            workspaceRoot: workspace.root,
+            workspaceRef: scope,
+        };
+    }
+    catch {
+        return fields;
+    }
+}
+export function computerOperationName(op) {
+    return computerOperationMap[op] ?? op;
+}
+function historyViewInput(op) {
+    return historyViewMap[op] ? { view: historyViewMap[op] } : {};
+}
+function stringValue(value, name) {
+    const text = optionalString(value);
+    if (!text)
+        throw new Error(`${name} is required`);
+    return text;
+}
+function optionalString(value) {
+    const text = String(value ?? "").trim();
+    return text || undefined;
+}
+function optionalPositiveInteger(value) {
+    const text = optionalString(value);
+    if (!text)
+        return undefined;
+    const parsed = Number.parseInt(text, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, 1000) : undefined;
+}
+function elapsedMs(started) {
+    return Math.max(0, Math.round(performance.now() - started));
+}
+function computerOperationError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: computerOperationErrorCode(error, message),
+        message,
+        retryable: isRetryableComputerOperationError(message),
+        details: error instanceof Error ? { name: error.name } : {},
+    };
+}
+function computerOperationErrorCode(error, message) {
+    if (/(^|\s)(scope|op|path|query|command|prompt|processId|operationName|workspace) is required\b/.test(message)) {
+        return "invalid_request";
+    }
+    if (/Unknown configured workspace|Unknown workspaceId/.test(message))
+        return "unknown_scope";
+    if (/outside workspace|outside exposed path|outside workspace root|resolves outside workspace|outside exposed paths/i.test(message)) {
+        return "path_out_of_scope";
+    }
+    if (/operation must be one of|Unknown operation|cannot execute operation|Unsupported Codex workflow/i.test(message)) {
+        return "unknown_operation";
+    }
+    if (error instanceof PermissionDeniedError || /permission is disabled|permission denied/i.test(message)) {
+        return "permission_denied";
+    }
+    if (/os permission|required.*permission|Screen Recording permission/i.test(message))
+        return "os_permission_required";
+    if (/provider.*unavailable|unavailable.*provider/i.test(message))
+        return "provider_unavailable";
+    if (/not implemented|unsupported platform|unsupported|not supported/i.test(message))
+        return "unsupported_platform";
+    if (/timed out|timeout/i.test(message))
+        return "timeout";
+    if (/Unknown process|process not found/i.test(message))
+        return "process_not_found";
+    return "execution_failed";
+}
+function isRetryableComputerOperationError(message) {
+    return /timed out|timeout|os permission|required.*permission|provider.*unavailable/i.test(message);
+}
+function runningTunnelPublicUrl(tunnels) {
+    return tunnels
+        .filter((tunnel) => tunnel.status === "running")
+        .map((tunnel) => tunnel.publicUrl)
+        .find((url) => Boolean(url));
+}
+function runningOpenAiTunnel(tunnels) {
+    return tunnels.find((tunnel) => tunnel.status === "running" && tunnel.provider === "openai");
+}
+function openAiTunnelIdFromSnapshot(tunnel) {
+    const args = Array.isArray(tunnel.args) ? tunnel.args : [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--control-plane.tunnel-id" && args[index + 1])
+            return args[index + 1];
+    }
+    return undefined;
+}
+function mcpClientSetupNextActions(remoteReady, remoteBlockingReasons, warnings, openAiTunnelId) {
+    if (remoteReady) {
+        if (openAiTunnelId) {
+            return [`Use OpenAI/ChatGPT Tunnel mode and select or paste ${openAiTunnelId}; the target MCP path remains /mcp.`, "Then call get_computer_info."];
+        }
+        return ["Use the public MCP URL with bearer auth or OAuth, then call get_computer_info."];
+    }
+    const actions = new Set();
+    actions.add("For local clients, use stdio or the loopback MCP URL.");
+    for (const reason of remoteBlockingReasons)
+        actions.add(`For remote clients, resolve: ${reason}`);
+    for (const warning of warnings)
+        actions.add(`Review: ${warning}`);
+    return [...actions];
+}

package/dist/computer-operation-registry.d.ts

@@ -0,0 +1,45 @@
+import { type PublicWorkspaceOperationRegistryEntry, type WorkspaceOperationName } from "./workspace-operations.js";
+export interface ComputerOperationEnvelope {
+    scope?: string;
+    op?: string;
+    target?: string;
+    input?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+}
+export interface ComputerOperationRegistryEntry {
+    op: string;
+    category: "file" | "code" | "git" | "package" | "command" | "process" | "codex" | "history" | "screen";
+    permission: PublicWorkspaceOperationRegistryEntry["permission"];
+    capabilities: PublicWorkspaceOperationRegistryEntry["capabilities"];
+    boundary: PublicWorkspaceOperationRegistryEntry["boundary"];
+    description: string;
+    target?: string;
+    requiredInput: string[];
+    optionalInput: string[];
+    options: string[];
+    backendOperation: WorkspaceOperationName;
+    legacyWorkspaceOperation: WorkspaceOperationName;
+    example: ComputerOperationEnvelope;
+}
+export interface ComputerOperationContract {
+    version: 1;
+    mcp: {
+        tool: "computer_operation";
+        requiredFields: ["scope", "op"];
+    };
+    jsonApi: {
+        endpoint: "POST /api/v1/control";
+        action: "computer_operation";
+        requiredFields: ["action", "scope", "op"];
+    };
+    envelope: ComputerOperationEnvelope;
+    guidance: string[];
+    compatibility: {
+        acceptsLegacyWorkspaceOps: true;
+        legacyRegistry: "operationRegistry";
+    };
+}
+export declare const computerOperationMap: Record<string, WorkspaceOperationName>;
+export declare const computerOperationContract: ComputerOperationContract;
+export declare const computerOperationRegistry: ComputerOperationRegistryEntry[];
+export declare function publicComputerOperationRegistry(): ComputerOperationRegistryEntry[];

package/dist/computer-operation-registry.js

@@ -0,0 +1,179 @@
+import { workspaceOperationEntry, } from "./workspace-operations.js";
+import { screenshotCapability } from "./screenshot.js";
+const computerOperationDefinitions = [
+    { op: "file.stat", category: "file", backendOperation: "stat", target: "path", description: "Return metadata for one scoped file or directory." },
+    { op: "file.list", category: "file", backendOperation: "list_details", target: "path", description: "List directory entries with type, size, and modified time." },
+    { op: "file.tree", category: "file", backendOperation: "tree", target: "path", description: "List a bounded recursive tree for codebase orientation." },
+    { op: "file.read", category: "file", backendOperation: "read", target: "path", description: "Read one UTF-8 file with optional byte or line bounds." },
+    { op: "file.read_many", category: "file", backendOperation: "read_many", description: "Read several UTF-8 files in one bounded scoped call." },
+    { op: "file.write", category: "file", backendOperation: "write", target: "path", description: "Create or overwrite one UTF-8 file inside the scope." },
+    { op: "file.create", category: "file", backendOperation: "create_file", target: "path", description: "Create one new UTF-8 file inside the scope and fail if it already exists." },
+    { op: "file.patch", category: "file", backendOperation: "patch", target: "path", description: "Apply a validated unified diff inside the scope." },
+    { op: "file.move", category: "file", backendOperation: "move", target: "fromPath", description: "Move or rename a scoped file or directory." },
+    { op: "file.delete", category: "file", backendOperation: "delete", target: "path", description: "Delete a scoped file or directory." },
+    { op: "file.find", category: "file", backendOperation: "find_files", target: "path", description: "Find scoped file paths by pattern." },
+    { op: "file.search", category: "file", backendOperation: "search_text", target: "path", description: "Search text quickly, preferring ripgrep when available." },
+    { op: "code.context", category: "code", backendOperation: "coding_context", target: "path", description: "Return a bounded code-oriented workspace context." },
+    { op: "code.search_symbols", category: "code", backendOperation: "search_symbols", target: "path", description: "Find common code symbols such as functions, classes, interfaces, and exports." },
+    { op: "git.status", category: "git", backendOperation: "repo_status", target: "path", description: "Inspect repository status and optional bounded diff." },
+    { op: "git.changes", category: "git", backendOperation: "git_changes", target: "path", description: "Return structured changed-file entries and counts." },
+    { op: "git.diff", category: "git", backendOperation: "git_diff", target: "path", description: "Return a bounded staged or unstaged diff." },
+    { op: "git.log", category: "git", backendOperation: "git_log", target: "path", description: "Return recent commits for a repository or pathspec." },
+    { op: "git.show", category: "git", backendOperation: "git_show", target: "path", description: "Return a bounded commit or object view." },
+    { op: "git.stage", category: "git", backendOperation: "git_stage", target: "path", description: "Stage scoped paths in the Git index." },
+    { op: "git.unstage", category: "git", backendOperation: "git_unstage", target: "path", description: "Unstage scoped paths from the Git index." },
+    { op: "git.commit", category: "git", backendOperation: "git_commit", target: "path", description: "Create a Git commit from staged scoped files." },
+    { op: "package.run", category: "package", backendOperation: "package_run", target: "path", description: "Run an existing package.json script in the scope." },
+    { op: "package.start", category: "package", backendOperation: "package_start", target: "path", description: "Start an existing package.json script as a managed process." },
+    { op: "command.run", category: "command", backendOperation: "command", target: "workingDirectory", description: "Run one bounded shell command in the scope." },
+    { op: "command.start", category: "command", backendOperation: "process_start", target: "workingDirectory", description: "Start a managed long-running shell process." },
+    { op: "command.read", category: "command", backendOperation: "process_read", target: "processId", description: "Read status and buffered output for a managed process." },
+    { op: "command.stop", category: "command", backendOperation: "process_stop", target: "processId", description: "Stop a managed process." },
+    { op: "command.list", category: "command", backendOperation: "process_list", description: "List managed shell and Codex processes for the scope." },
+    { op: "process.start", category: "process", backendOperation: "process_start", target: "workingDirectory", description: "Start a managed long-running shell process." },
+    { op: "process.read", category: "process", backendOperation: "process_read", target: "processId", description: "Read status and buffered output for a managed process." },
+    { op: "process.stop", category: "process", backendOperation: "process_stop", target: "processId", description: "Stop a managed process." },
+    { op: "process.list", category: "process", backendOperation: "process_list", description: "List managed processes for the scope." },
+    { op: "codex.run", category: "codex", backendOperation: "codex", target: "workingDirectory", description: "Run the local Codex CLI once in the scope." },
+    { op: "codex.start", category: "codex", backendOperation: "codex_start", target: "workingDirectory", description: "Start a managed Codex CLI task." },
+    { op: "codex.read", category: "codex", backendOperation: "codex_runs", target: "workflowId", description: "Read persisted Codex run records." },
+    { op: "codex.stop", category: "codex", backendOperation: "process_stop", target: "processId", description: "Stop a managed Codex process." },
+    { op: "codex.list", category: "codex", backendOperation: "codex_runs", description: "List recent persisted Codex run records." },
+    { op: "history.last", category: "history", backendOperation: "history_insight", description: "Return the latest redacted operation summary." },
+    { op: "history.timeline", category: "history", backendOperation: "history_insight", description: "Return a redacted operation timeline." },
+    { op: "history.sessions", category: "history", backendOperation: "history_insight", description: "Return recent session summaries." },
+    { op: "history.connections", category: "history", backendOperation: "history_insight", description: "Return tunnel and MCP connection summaries." },
+    { op: "history.failed_replay", category: "history", backendOperation: "history_insight", description: "Return failed-operation replay templates." },
+    { op: "history.debug_bundle", category: "history", backendOperation: "history_insight", description: "Export a redacted debug bundle." },
+    { op: "screen.list", category: "screen", backendOperation: "screen_list", description: "List screenshot provider readiness, displays, and capturable windows/processes when available." },
+    { op: "screen.capture", category: "screen", backendOperation: "screen_capture", target: "displayId", backendTarget: "path", description: "Capture the primary display or selected display when supported." },
+    { op: "screen.capture_window", category: "screen", backendOperation: "screen_capture_window", target: "windowId", backendTarget: "path", description: "Capture a visible window by id when supported." },
+    { op: "screen.capture_process", category: "screen", backendOperation: "screen_capture_process", target: "processIdOrName", backendTarget: "path", description: "Capture a visible window for a process id or process name when supported." },
+];
+export const computerOperationMap = Object.fromEntries(computerOperationDefinitions.map((entry) => [entry.op, entry.backendOperation]));
+const computerOperationExamples = {
+    "file.stat": { scope: "app", op: "file.stat", target: "README.md" },
+    "file.list": { scope: "app", op: "file.list", target: "src" },
+    "file.tree": { scope: "app", op: "file.tree", target: ".", options: { maxDepth: 2, maxEntries: 100 } },
+    "file.read": { scope: "app", op: "file.read", target: "README.md", options: { maxBytes: 65536 } },
+    "file.read_many": { scope: "app", op: "file.read_many", input: { paths: ["README.md", "package.json"] }, options: { maxBytes: 65536 } },
+    "file.write": { scope: "app", op: "file.write", target: "notes/todo.md", input: { content: "- item\n" } },
+    "file.create": { scope: "app", op: "file.create", target: "notes/todo.md", input: { content: "- item\n" } },
+    "file.patch": { scope: "app", op: "file.patch", input: { patch: "diff --git a/README.md b/README.md\n--- a/README.md\n+++ b/README.md\n@@ -1 +1 @@\n-old\n+new\n" } },
+    "file.move": { scope: "app", op: "file.move", input: { fromPath: "old.txt", toPath: "archive/old.txt" } },
+    "file.delete": { scope: "app", op: "file.delete", target: "tmp/output", input: { recursive: true } },
+    "file.find": { scope: "app", op: "file.find", target: ".", input: { pattern: "*.ts" }, options: { maxResults: 50 } },
+    "file.search": { scope: "app", op: "file.search", target: ".", input: { query: "TODO", glob: "*.ts" }, options: { maxResults: 20 } },
+    "code.context": { scope: "app", op: "code.context", target: ".", options: { maxDepth: 2, maxEntries: 100, maxBytes: 32768 } },
+    "code.search_symbols": { scope: "app", op: "code.search_symbols", target: ".", input: { query: "Workspace", glob: "*.ts" }, options: { maxResults: 50 } },
+    "git.status": { scope: "app", op: "git.status", target: ".", input: { includeDiff: true }, options: { maxBytes: 65536 } },
+    "git.changes": { scope: "app", op: "git.changes", target: "." },
+    "git.diff": { scope: "app", op: "git.diff", target: ".", input: { paths: ["src/index.ts"], staged: false }, options: { maxBytes: 65536 } },
+    "git.log": { scope: "app", op: "git.log", target: ".", input: { paths: ["src/index.ts"] }, options: { maxResults: 20 } },
+    "git.show": { scope: "app", op: "git.show", target: ".", input: { ref: "HEAD", paths: ["src/index.ts"] }, options: { maxBytes: 65536 } },
+    "git.stage": { scope: "app", op: "git.stage", target: ".", input: { paths: ["src/index.ts", "README.md"] } },
+    "git.unstage": { scope: "app", op: "git.unstage", target: ".", input: { paths: ["src/index.ts"] } },
+    "git.commit": { scope: "app", op: "git.commit", target: ".", input: { message: "Implement workspace search" } },
+    "package.run": { scope: "app", op: "package.run", target: ".", input: { script: "test", scriptArgs: ["--watch=false"] }, options: { timeoutSeconds: 120, maxOutputBytes: 200000 } },
+    "package.start": { scope: "app", op: "package.start", target: ".", input: { script: "dev", scriptArgs: ["--host", "127.0.0.1"] }, options: { timeoutSeconds: 3600, maxOutputBytes: 200000 } },
+    "command.run": { scope: "app", op: "command.run", target: ".", input: { command: "npm test" }, options: { timeoutSeconds: 600 } },
+    "command.start": { scope: "app", op: "command.start", target: ".", input: { command: "npm run dev" }, options: { timeoutSeconds: 3600 } },
+    "command.read": { scope: "app", op: "command.read", input: { processId: "proc_..." } },
+    "command.stop": { scope: "app", op: "command.stop", input: { processId: "proc_..." } },
+    "command.list": { scope: "app", op: "command.list" },
+    "process.start": { scope: "app", op: "process.start", target: ".", input: { command: "npm run dev" }, options: { timeoutSeconds: 3600 } },
+    "process.read": { scope: "app", op: "process.read", target: "proc_..." },
+    "process.stop": { scope: "app", op: "process.stop", target: "proc_..." },
+    "process.list": { scope: "app", op: "process.list" },
+    "codex.run": { scope: "app", op: "codex.run", target: ".", input: { prompt: "Inspect this repo and summarize failing tests." }, options: { timeoutSeconds: 1800 } },
+    "codex.start": { scope: "app", op: "codex.start", target: ".", input: { prompt: "Run tests and summarize failures." }, options: { timeoutSeconds: 1800 } },
+    "codex.read": { scope: "app", op: "codex.read", input: { workflowId: "codex_fix_..." } },
+    "codex.stop": { scope: "app", op: "codex.stop", target: "proc_..." },
+    "codex.list": { scope: "app", op: "codex.list", options: { maxResults: 10 } },
+    "history.last": { scope: "app", op: "history.last" },
+    "history.timeline": { scope: "app", op: "history.timeline", options: { maxResults: 50 } },
+    "history.sessions": { scope: "app", op: "history.sessions", options: { maxResults: 20 } },
+    "history.connections": { scope: "app", op: "history.connections", options: { maxResults: 20 } },
+    "history.failed_replay": { scope: "app", op: "history.failed_replay", options: { maxResults: 20 } },
+    "history.debug_bundle": { scope: "app", op: "history.debug_bundle", options: { maxResults: 100 } },
+    "screen.list": { scope: "app", op: "screen.list" },
+    "screen.capture": { scope: "app", op: "screen.capture", target: "primary", options: { returnMode: "fileRef", format: "png" } },
+    "screen.capture_window": { scope: "app", op: "screen.capture_window", target: "window-1", options: { returnMode: "fileRef", format: "png" } },
+    "screen.capture_process": { scope: "app", op: "screen.capture_process", target: "Terminal", options: { returnMode: "fileRef", format: "png" } },
+};
+export const computerOperationContract = {
+    version: 1,
+    mcp: {
+        tool: "computer_operation",
+        requiredFields: ["scope", "op"],
+    },
+    jsonApi: {
+        endpoint: "POST /api/v1/control",
+        action: "computer_operation",
+        requiredFields: ["action", "scope", "op"],
+    },
+    envelope: {
+        scope: "app",
+        op: "file.read",
+        target: "README.md",
+        input: {},
+        options: { maxBytes: 65536 },
+    },
+    guidance: [
+        "Keep the outer envelope stable: scope, op, target, input, options.",
+        "Use the generic dotted op names for new clients, such as file.read, file.search, code.context, git.diff, package.run, command.run, process.start, codex.run, screen.capture, and history.last.",
+        "Put operation-specific payload in input and bounds such as maxBytes, maxResults, and timeoutSeconds in options.",
+        "Choose scope from get_computer_info.scopes and check the returned operation registry before write, command, or Codex operations.",
+    ],
+    compatibility: {
+        acceptsLegacyWorkspaceOps: true,
+        legacyRegistry: "operationRegistry",
+    },
+};
+export const computerOperationRegistry = computerOperationDefinitions.map((definition) => {
+    const backend = workspaceOperationEntry(definition.backendOperation);
+    const optionFields = new Set(["maxBytes", "maxOutputBytes", "maxResults", "timeoutSeconds", "maxDepth", "maxEntries", "startLine", "lineCount", "beforeContext", "afterContext", "format", "returnMode", "maxWidth", "maxHeight"]);
+    const backendTarget = definition.backendTarget ?? definition.target;
+    const requiredInput = backend.requiredFields.filter((field) => field !== backendTarget);
+    const optionalInput = backend.optionalFields.filter((field) => field !== backendTarget && !optionFields.has(field));
+    const options = backend.optionalFields.filter((field) => optionFields.has(field));
+    return {
+        op: definition.op,
+        category: definition.category,
+        permission: backend.permission,
+        capabilities: backend.capabilities,
+        boundary: backend.boundary,
+        description: definition.description,
+        target: definition.target,
+        requiredInput,
+        optionalInput,
+        options,
+        backendOperation: definition.backendOperation,
+        legacyWorkspaceOperation: definition.backendOperation,
+        example: computerOperationExamples[definition.op] ?? {
+            ...computerOperationContract.envelope,
+            op: definition.op,
+        },
+    };
+});
+export function publicComputerOperationRegistry() {
+    return computerOperationRegistry.filter((operation) => operationSupportedByCurrentRuntime(operation));
+}
+function operationSupportedByCurrentRuntime(operation) {
+    if (operation.op === "screen.list")
+        return true;
+    const screenMode = screenCaptureModeForOperation(operation.backendOperation);
+    if (!screenMode)
+        return true;
+    const capability = screenshotCapability();
+    return capability.supported && capability.modes.includes(screenMode);
+}
+function screenCaptureModeForOperation(operation) {
+    if (operation === "screen_capture")
+        return "display";
+    if (operation === "screen_capture_window")
+        return "window";
+    if (operation === "screen_capture_process")
+        return "process";
+    return undefined;
+}