@easonwumac/computer-linker 0.1.2

package/dist/history-insights.js

@@ -0,0 +1,457 @@
+import { auditLogPath } from "./config.js";
+import { readAuditEvents } from "./audit.js";
+import { listTunnelProcesses, tunnelRuntimeEvents } from "./tunnels.js";
+export function historyInsight(options = {}) {
+    const view = historyInsightView(options.view);
+    const limit = normalizeLimit(options.limit);
+    const events = options.events ?? readAuditEvents({
+        workspaceId: options.workspaceId,
+        query: options.query,
+        limit,
+    });
+    const mergedEvents = mergeDerivedHistoryEvents(events, {
+        ...options,
+        view,
+        limit,
+    });
+    return historyInsightFromEvents(mergedEvents, {
+        view,
+        limit,
+        query: options.query,
+        workspaceId: options.workspaceId,
+    });
+}
+export function historyInsightFromEvents(events, options = {}) {
+    const view = historyInsightView(options.view);
+    const limit = normalizeLimit(options.limit);
+    const compactEvents = events.slice(0, limit).map(compactAuditEvent);
+    const summary = {
+        totalEvents: compactEvents.length,
+        successfulEvents: compactEvents.filter((event) => event.success).length,
+        failedEvents: compactEvents.filter((event) => !event.success).length,
+        lastEvent: compactEvents[0],
+        lastWorkspaceOperation: compactEvents.find(isOperationAuditEvent),
+        recentFailures: compactEvents.filter((event) => !event.success).slice(0, 10),
+        toolCounts: counts(compactEvents.map((event) => event.tool ?? event.type)),
+        workspaceCounts: counts(compactEvents.map((event) => event.workspaceId ?? event.workspaceRef).filter((value) => Boolean(value))),
+    };
+    const failedReplay = buildFailedReplay(compactEvents);
+    const sessions = buildSessionSummaries(compactEvents);
+    const connections = buildConnectionSummaries(compactEvents);
+    const last = buildLastInsight(summary, sessions, connections, failedReplay);
+    const insight = {
+        view,
+        generatedAt: new Date().toISOString(),
+        filters: {
+            workspaceId: options.workspaceId,
+            query: options.query,
+            limit,
+        },
+        summary,
+    };
+    if (view === "last" || view === "debug_bundle") {
+        insight.last = last;
+    }
+    if (view === "timeline" || view === "debug_bundle") {
+        insight.timeline = [...compactEvents].reverse();
+    }
+    if (view === "sessions" || view === "debug_bundle") {
+        insight.sessions = sessions;
+    }
+    if (view === "connections" || view === "debug_bundle") {
+        insight.connections = connections;
+    }
+    if (view === "failed_replay" || view === "debug_bundle") {
+        insight.failedReplay = failedReplay;
+    }
+    if (view === "debug_bundle") {
+        insight.debugBundle = {
+            format: "computer-linker-debug-bundle-v1",
+            auditLogPath: auditLogPath(),
+            redactions: [
+                "Owner tokens and OAuth tokens are not written to the audit log.",
+                "File contents, patch bodies, write payloads, screenshot image bytes, and full command prompts are not included.",
+                "commandPreview is truncated to a short diagnostic preview.",
+                "Tunnel-client raw logs are converted to compact tunnel_event rows; full tunnel stderr/stdout is not exported.",
+            ],
+            events: compactEvents,
+            connections,
+            failedReplay,
+        };
+    }
+    return insight;
+}
+export function historyInsightView(value) {
+    if (value === "last" || value === "timeline" || value === "sessions" || value === "connections" || value === "failed_replay" || value === "debug_bundle")
+        return value;
+    return "summary";
+}
+function buildLastInsight(summary, sessions, connections, failedReplay) {
+    const failure = summary.recentFailures[0];
+    const replay = failure
+        ? failedReplay.find((item) => item.timestamp === failure.timestamp)
+        : undefined;
+    return {
+        event: summary.lastEvent,
+        workspaceOperation: summary.lastWorkspaceOperation,
+        failure,
+        replay,
+        session: sessions[0],
+        connection: connections[0],
+        suggestedNextActions: lastInsightNextActions(summary, replay),
+    };
+}
+function lastInsightNextActions(summary, replay) {
+    const actions = [];
+    if (summary.recentFailures.some((event) => event.type === "tunnel_event")) {
+        actions.push("Call history_insight with view=connections to inspect tunnel sessions and request IDs.");
+    }
+    if (summary.failedEvents > 0) {
+        actions.push("Call history_insight with view=failed_replay to inspect replay templates for recent failures.");
+    }
+    if (replay?.replayable) {
+        actions.push("Replay the failed operation after confirming the workspace and target are still correct.");
+    }
+    else if (replay?.requiresInput?.length) {
+        actions.push(`Ask for or reconstruct missing replay input: ${replay.requiresInput.join(", ")}.`);
+    }
+    if (summary.lastWorkspaceOperation) {
+        actions.push("Call history_insight with view=timeline and a small limit if more context is needed.");
+    }
+    if (actions.length === 0) {
+        actions.push("No recent failure was found; continue with the next requested workspace operation.");
+    }
+    return actions;
+}
+function compactAuditEvent(event) {
+    return {
+        timestamp: event.timestamp,
+        type: event.type,
+        success: event.success,
+        tool: event.tool,
+        workspaceId: event.workspaceId,
+        workspaceRef: event.workspaceRef,
+        requestPath: event.requestPath,
+        remoteAddress: event.remoteAddress,
+        path: event.path,
+        workingDirectory: event.workingDirectory,
+        commandPreview: event.commandPreview,
+        operation: event.operation,
+        target: event.target,
+        detail: event.detail,
+        replay: event.replay,
+        error: event.error,
+        durationMs: event.durationMs,
+        provider: event.provider,
+        tunnelId: event.tunnelId,
+        externalSessionId: event.externalSessionId,
+        requestId: event.requestId,
+        cmdRequestId: event.cmdRequestId,
+        rpcRequestId: event.rpcRequestId,
+        tunnelRequestId: event.tunnelRequestId,
+        severity: event.severity,
+        statusCode: event.statusCode,
+    };
+}
+function mergeDerivedHistoryEvents(events, options) {
+    const view = historyInsightView(options.view);
+    const limit = normalizeLimit(options.limit);
+    const includeInfo = view === "connections" || view === "debug_bundle";
+    const derivedEvents = tunnelRuntimeEvents(listTunnelProcesses(), {
+        includeInfo,
+        limit: includeInfo ? Math.max(limit, 200) : Math.min(limit, 100),
+    })
+        .map(tunnelRuntimeEventToAuditEvent)
+        .filter((event) => historyEventMatchesFilters(event, options));
+    return [...events, ...derivedEvents]
+        .filter((event) => historyEventMatchesFilters(event, options))
+        .sort((a, b) => b.timestamp.localeCompare(a.timestamp))
+        .slice(0, limit);
+}
+function tunnelRuntimeEventToAuditEvent(event) {
+    const success = event.severity === "info";
+    const detail = tunnelAuditDetail(event);
+    return {
+        timestamp: event.timestamp,
+        type: "tunnel_event",
+        success,
+        tool: `tunnel:${event.provider}`,
+        requestPath: event.rpcMethod,
+        remoteAddress: event.tunnelRequestId,
+        operation: event.kind,
+        detail,
+        error: success ? undefined : event.detail ?? event.message,
+        provider: event.provider,
+        tunnelId: event.tunnelId,
+        externalSessionId: event.sessionId,
+        requestId: event.requestId,
+        cmdRequestId: event.cmdRequestId,
+        rpcRequestId: event.rpcRequestId,
+        tunnelRequestId: event.tunnelRequestId,
+        severity: event.severity,
+        statusCode: event.statusCode,
+    };
+}
+function tunnelAuditDetail(event) {
+    return [
+        event.message,
+        event.rpcMethod,
+        event.statusCode === undefined ? undefined : `status=${event.statusCode}`,
+        event.detail,
+    ].filter(Boolean).join(" · ");
+}
+function historyEventMatchesFilters(event, options) {
+    if (options.workspaceId && event.workspaceId !== options.workspaceId && event.workspaceRef !== options.workspaceId) {
+        return false;
+    }
+    if (options.query && !historySearchText(event).includes(options.query.toLowerCase())) {
+        return false;
+    }
+    return true;
+}
+function historySearchText(event) {
+    return [
+        event.timestamp,
+        event.type,
+        event.tool,
+        event.workspaceId,
+        event.workspaceRoot,
+        event.workspaceRef,
+        event.path,
+        event.requestPath,
+        event.remoteAddress,
+        event.workingDirectory,
+        event.commandPreview,
+        event.operation,
+        event.target,
+        event.detail,
+        event.error,
+        event.provider,
+        event.tunnelId,
+        event.externalSessionId,
+        event.requestId,
+        event.cmdRequestId,
+        event.rpcRequestId,
+        event.tunnelRequestId,
+        event.severity,
+        event.statusCode === undefined ? undefined : String(event.statusCode),
+    ]
+        .filter(Boolean)
+        .join("\n")
+        .toLowerCase();
+}
+function isOperationAuditEvent(event) {
+    return event.tool === "computer_operation" ||
+        event.tool === "workspace_operation" ||
+        event.tool === "workspace_operation.batch_item";
+}
+function buildSessionSummaries(events) {
+    const groups = new Map();
+    for (const event of events) {
+        const key = sessionKey(event);
+        groups.set(key, [...(groups.get(key) ?? []), event]);
+    }
+    return [...groups.entries()]
+        .map(([key, sessionEvents]) => {
+        const newest = sessionEvents[0];
+        const oldest = sessionEvents[sessionEvents.length - 1];
+        const workspaceRef = newest.workspaceRef ?? newest.workspaceId;
+        const workspaceId = newest.workspaceId;
+        const surface = sessionSurface(newest);
+        const scope = key.startsWith("workspace:") ? "workspace" : "surface";
+        return {
+            key,
+            scope,
+            workspaceId,
+            workspaceRef,
+            surface,
+            startedAt: oldest.timestamp,
+            lastActivityAt: newest.timestamp,
+            totalEvents: sessionEvents.length,
+            successfulEvents: sessionEvents.filter((event) => event.success).length,
+            failedEvents: sessionEvents.filter((event) => !event.success).length,
+            tools: counts(sessionEvents.map((event) => event.tool ?? event.type)),
+            operations: counts(sessionEvents.map((event) => event.operation).filter((value) => Boolean(value))),
+            lastEvent: newest,
+            recentFailures: sessionEvents.filter((event) => !event.success).slice(0, 5),
+        };
+    })
+        .sort((left, right) => right.lastActivityAt.localeCompare(left.lastActivityAt));
+}
+function buildConnectionSummaries(events) {
+    const groups = new Map();
+    for (const event of events) {
+        const key = connectionKey(event);
+        if (!key)
+            continue;
+        groups.set(key, [...(groups.get(key) ?? []), event]);
+    }
+    return [...groups.entries()]
+        .map(([key, connectionEvents]) => {
+        const newest = connectionEvents[0];
+        const oldest = connectionEvents[connectionEvents.length - 1];
+        const requestIds = new Set(connectionEvents.flatMap((event) => ([event.requestId, event.cmdRequestId, event.rpcRequestId, event.tunnelRequestId].filter((value) => Boolean(value)))));
+        return {
+            key,
+            scope: connectionScope(key),
+            provider: newest.provider,
+            tunnelId: newest.tunnelId,
+            externalSessionId: newest.externalSessionId,
+            remoteAddress: newest.remoteAddress,
+            startedAt: oldest.timestamp,
+            lastActivityAt: newest.timestamp,
+            totalEvents: connectionEvents.length,
+            successfulEvents: connectionEvents.filter((event) => event.success).length,
+            failedEvents: connectionEvents.filter((event) => !event.success).length,
+            requestCount: requestIds.size,
+            tools: counts(connectionEvents.map((event) => event.tool ?? event.type)),
+            operations: counts(connectionEvents.map((event) => event.operation).filter((value) => Boolean(value))),
+            lastEvent: newest,
+            recentFailures: connectionEvents.filter((event) => !event.success).slice(0, 5),
+        };
+    })
+        .sort((left, right) => right.lastActivityAt.localeCompare(left.lastActivityAt));
+}
+function connectionKey(event) {
+    if (event.externalSessionId)
+        return `tunnel:${event.provider ?? "unknown"}:${event.externalSessionId}`;
+    if (event.tunnelId)
+        return `tunnel:${event.provider ?? "unknown"}:${event.tunnelId}`;
+    const mcpSessionId = mcpSessionIdFromEvent(event);
+    if (mcpSessionId)
+        return `mcp:${mcpSessionId}`;
+    const workspace = event.workspaceId ?? event.workspaceRef;
+    if (workspace)
+        return `workspace:${workspace}`;
+    if (event.remoteAddress)
+        return `surface:${event.remoteAddress}`;
+    return event.tool || event.requestPath ? `surface:${sessionSurface(event)}` : undefined;
+}
+function connectionScope(key) {
+    if (key.startsWith("tunnel:"))
+        return "tunnel";
+    if (key.startsWith("mcp:"))
+        return "mcp";
+    if (key.startsWith("workspace:"))
+        return "workspace";
+    return "surface";
+}
+function mcpSessionIdFromEvent(event) {
+    if (event.type !== "mcp_session" || !event.detail)
+        return undefined;
+    const match = /(?:created|session):\s*([A-Za-z0-9_.:-]+)/.exec(event.detail);
+    return match?.[1];
+}
+function sessionKey(event) {
+    const workspace = event.workspaceId ?? event.workspaceRef;
+    if (workspace)
+        return `workspace:${workspace}`;
+    return `surface:${sessionSurface(event)}`;
+}
+function sessionSurface(event) {
+    return event.tool ?? event.requestPath ?? event.type;
+}
+function buildFailedReplay(events) {
+    return events
+        .filter((event) => !event.success)
+        .slice(0, 20)
+        .map((event) => {
+        const workspace = event.workspaceId ?? event.workspaceRef;
+        const op = event.operation ?? inferOperation(event);
+        if (!workspace || !op || (event.tool !== "workspace_operation" && event.tool !== "workspace_operation.batch_item")) {
+            return {
+                timestamp: event.timestamp,
+                error: event.error,
+                replayable: false,
+                reason: "Audit event does not contain enough workspace operation metadata to build a replay request.",
+            };
+        }
+        if (event.replay) {
+            return replayItemFromTemplate(event, workspace, event.replay);
+        }
+        const target = event.target ?? event.path ?? event.workingDirectory;
+        const requiresInput = sensitiveReplayInputs(op);
+        return {
+            timestamp: event.timestamp,
+            error: event.error,
+            replayable: requiresInput.length === 0,
+            reason: requiresInput.length > 0
+                ? `Full ${requiresInput.join("/")} text is not stored in old audit events; provide it before replaying.`
+                : event.commandPreview ? "Replay uses stored operation metadata; command/prompt text is only available as a truncated preview." : undefined,
+            requiresInput: requiresInput.length > 0 ? requiresInput : undefined,
+            request: {
+                action: "workspace_operation",
+                workspace,
+                input: {
+                    op,
+                    target,
+                    input: replayInput(event),
+                    options: {},
+                },
+            },
+        };
+    });
+}
+function replayItemFromTemplate(event, workspace, replay) {
+    return {
+        timestamp: event.timestamp,
+        error: event.error,
+        replayable: replay.replayable,
+        reason: replay.reason,
+        requiresInput: replay.requiresInput,
+        request: {
+            action: replay.action,
+            workspace,
+            input: replay.input,
+        },
+    };
+}
+function replayInput(event) {
+    if (event.operation === "package_run" || event.operation === "package_start") {
+        return event.detail ? { script: event.detail } : {};
+    }
+    if (event.operation === "search_text") {
+        return event.detail ? { query: event.detail } : {};
+    }
+    if (event.operation === "find_files") {
+        return event.detail ? { pattern: event.detail } : {};
+    }
+    if (event.operation === "process_read" || event.operation === "process_stop") {
+        return event.detail ? { processId: event.detail } : {};
+    }
+    return {};
+}
+function sensitiveReplayInputs(op) {
+    if (op === "command" || op === "process_start")
+        return ["command"];
+    if (op === "codex" ||
+        op === "codex_start" ||
+        op === "codex_plan" ||
+        op === "codex_review" ||
+        op === "codex_fix" ||
+        op === "codex_test" ||
+        op === "codex_continue") {
+        return ["prompt"];
+    }
+    return [];
+}
+function inferOperation(event) {
+    if (!event.detail)
+        return undefined;
+    const batchMatch = /^batch\[\d+\]:\s+([a-z_]+)$/.exec(event.detail);
+    if (batchMatch)
+        return batchMatch[1];
+    if (/^[a-z_]+$/.test(event.detail))
+        return event.detail;
+    return undefined;
+}
+function counts(values) {
+    const result = {};
+    for (const value of values) {
+        result[value] = (result[value] ?? 0) + 1;
+    }
+    return result;
+}
+function normalizeLimit(value) {
+    return Number.isInteger(value) && value && value > 0 ? Math.min(value, 1000) : 200;
+}

package/dist/http-auth.d.ts

@@ -0,0 +1,3 @@
+import type { Request } from "express";
+export declare function isAuthorizedLocalPortRequest(req: Request, ownerToken: string | undefined): boolean;
+export declare function isLoopbackRequest(req: Request): boolean;

package/dist/http-auth.js

@@ -0,0 +1,15 @@
+export function isAuthorizedLocalPortRequest(req, ownerToken) {
+    if (!ownerToken)
+        return isLoopbackRequest(req);
+    const authorization = req.header("authorization") ?? "";
+    const bearerPrefix = "Bearer ";
+    if (authorization.startsWith(bearerPrefix) && authorization.slice(bearerPrefix.length) === ownerToken) {
+        return true;
+    }
+    return req.header("x-computer-linker-token") === ownerToken ||
+        req.header("x-workspace-linker-token") === ownerToken ||
+        req.header("x-localport-token") === ownerToken;
+}
+export function isLoopbackRequest(req) {
+    return req.ip === "127.0.0.1" || req.ip === "::1" || req.ip === "::ffff:127.0.0.1";
+}

package/dist/mcp-surface.d.ts

@@ -0,0 +1,5 @@
+export type McpToolSurface = "generic" | "compatibility";
+export declare const genericMcpTools: readonly ["get_computer_info", "computer_operation", "get_operation_history"];
+export declare const compatibilityMcpTools: readonly ["get_capabilities", "list_workspaces", "open_workspace", "read", "ls", "grep", "glob", "create_file", "workspace_operation"];
+export declare function mcpToolSurface(): McpToolSurface;
+export declare function exposedMcpTools(surface?: McpToolSurface): string[];

package/dist/mcp-surface.js

@@ -0,0 +1,25 @@
+export const genericMcpTools = ["get_computer_info", "computer_operation", "get_operation_history"];
+export const compatibilityMcpTools = [
+    "get_capabilities",
+    "list_workspaces",
+    "open_workspace",
+    "read",
+    "ls",
+    "grep",
+    "glob",
+    "create_file",
+    "workspace_operation",
+];
+export function mcpToolSurface() {
+    const raw = (process.env.COMPUTER_LINKER_MCP_TOOL_SURFACE ?? process.env.WORKSPACE_LINKER_MCP_TOOL_SURFACE ?? process.env.LOCALPORT_MCP_TOOL_SURFACE ?? "generic")
+        .trim()
+        .toLowerCase();
+    if (raw === "compatibility" || raw === "legacy" || raw === "all")
+        return "compatibility";
+    return "generic";
+}
+export function exposedMcpTools(surface = mcpToolSurface()) {
+    return surface === "compatibility"
+        ? [...genericMcpTools, ...compatibilityMcpTools]
+        : [...genericMcpTools];
+}

package/dist/oauth-provider.d.ts

@@ -0,0 +1,52 @@
+import type { Response } from "express";
+import type { OAuthRegisteredClientsStore } from "@modelcontextprotocol/sdk/server/auth/clients.js";
+import type { AuthorizationParams, OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { OAuthClientInformationFull, OAuthTokenRevocationRequest, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+export interface LocalPortOAuthConfig {
+    ownerToken: string;
+    scopes: string[];
+    accessTokenTtlSeconds: number;
+    refreshTokenTtlSeconds: number;
+}
+interface TokenRecord {
+    clientId: string;
+    scopes: string[];
+    expiresAt: number;
+    resource?: string;
+}
+export declare class OAuthStateStore implements OAuthRegisteredClientsStore {
+    private readonly statePath?;
+    private readonly clients;
+    private readonly accessTokens;
+    private readonly refreshTokens;
+    constructor(statePath?: string | undefined);
+    getClient(clientId: string): OAuthClientInformationFull | undefined;
+    registerClient(client: Omit<OAuthClientInformationFull, "client_id" | "client_id_issued_at">): OAuthClientInformationFull;
+    getAccessToken(token: string): TokenRecord | undefined;
+    setAccessToken(token: string, record: TokenRecord): void;
+    deleteAccessToken(token: string): void;
+    getRefreshToken(token: string): TokenRecord | undefined;
+    setRefreshToken(token: string, record: TokenRecord): void;
+    deleteRefreshToken(token: string): void;
+    private pruneExpiredTokens;
+    private save;
+}
+export declare class LocalPortOAuthProvider implements OAuthServerProvider {
+    private readonly config;
+    readonly clientsStore: OAuthStateStore;
+    private readonly codes;
+    private readonly resourceServerUrl;
+    constructor(config: LocalPortOAuthConfig, mcpServerUrl: URL, options?: {
+        statePath?: string;
+    });
+    authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
+    challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;
+    exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string, _codeVerifier?: string, redirectUri?: string, resource?: URL): Promise<OAuthTokens>;
+    exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[], resource?: URL): Promise<OAuthTokens>;
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+    revokeToken(_client: OAuthClientInformationFull, request: OAuthTokenRevocationRequest): Promise<void>;
+    private validCodeRecord;
+    private issueTokens;
+}
+export {};