impel-cli 0.18.14 → 0.18.15-beta.1

package/README.md

@@ -100,6 +100,50 @@ app opens. Tenant variants can remain installed side by side.
 
 Linux does not have managed desktop apps. Use the isolated CLI commands there.
 
+## Experimental managed Cursor
+
+On macOS, a hidden experiment can prepare an isolated Cursor runtime for the
+selected Impel tenant:
+
+```sh
+impel experimental cursor prepare
+impel experimental cursor open [workspace]
+impel experimental cursor status
+```
+
+The experiment never modifies `/Applications/Cursor.app` or the native Cursor
+profile. It verifies the installed stable app's Developer ID signature, mirrors
+it into the selected tenant's Impel-managed directory, enables Cursor's bundled
+local-agent runtime with fail-closed fixed-width patches, verifies extension
+integrity and signing, and prepares a tenant-only home, user-data directory,
+and extension directory. Cursor's local-mode profile-import service is disabled
+so it cannot inspect or copy the native Cursor profile. The managed bundle
+recomputes Cursor's signed-source checksum table after its reviewed patches, and
+the launcher uses Cursor's process-lifetime secret store because no persistent
+Cursor account or provider secret belongs in this tenant runtime.
+
+The native Cursor installation continues to update through Cursor. Every
+`prepare` inspects it again and atomically rebuilds the managed copy
+when a compatible version or commit changes. If Cursor changes any reviewed
+local-agent, provider-priority, or model-transport source contract, Impel keeps
+the previous managed generation intact and refuses the update until the patch is
+reviewed. `experimental cursor open` performs this prepare step before every
+launch. A real packaged GUI battle test proves that Cursor 3.12.17 can run
+Agent through the selected tenant's gateway with Cursor's own non-secret smoke
+identity. The logical `default` model is resolved by the gateway to its
+registered Cursor default; explicit gateway models continue to use Responses.
+
+This is not complete hosted-Cursor parity or an offline Cursor.
+The managed local transport supports Agent chat, edits, terminal tools, MCP,
+vision, reasoning, and gateway model discovery, and projects the live tenant
+catalog into Cursor's model picker, but the current vendor build explicitly
+disables hosted-only features such as Tab completion, cloud Background Agents,
+shared chats/canvases, Bugbot, and server-side repository indexing in local
+mode. Enabling those paths would either send work to Cursor-hosted models or
+require additional unpublished Cursor protocols, so the experiment does not
+claim or silently emulate them. See
+[`docs/experimental-managed-cursor.md`](docs/experimental-managed-cursor.md).
+
 ## Use the CLI
 
 Select the tenant used by CLI launches:
@@ -362,8 +406,8 @@ feature flags; an extension cannot add an upstream command family.
 The project is dependency-free at runtime and uses Node's built-in test runner:
 
 ```sh
-npm test
-npm pack --dry-run
+pnpm test
+pnpm pack --dry-run
 ```
 
 Tests use temporary homes, injected process runners, fake catalogs, and local

package/docs/experimental-managed-cursor.md

@@ -0,0 +1,205 @@
+# Experimental managed Cursor
+
+This hidden macOS experiment runs the stable Cursor desktop Agent against the
+selected Impel tenant without a real Cursor account or Cursor-routed BYOK. It is
+validated against Cursor 3.12.17 and remains separate from the public
+`impel setup` / `impel update` state machine:
+
+```sh
+impel experimental cursor prepare
+impel experimental cursor status
+impel experimental cursor open [workspace-or-Cursor-args...]
+```
+
+## Why standard BYOK is insufficient
+
+Cursor's supported BYOK mode still sends provider keys and requests through
+Cursor's backend, applies only to chat models, and keeps Tab on Cursor-hosted
+models. It cannot provide direct, tenant-scoped Impel inference.
+
+The stable desktop bundle also contains a dormant local-agent runtime with
+OpenAI Responses, Chat Completions, Anthropic Messages, `/models` discovery,
+tools, streaming, reasoning, vision, and MCP support. Impel enables only the
+exact reviewed local-mode signatures and locks provider resolution to its
+process environment.
+
+## Managed authentication
+
+Cursor's packaged Agent UI considers a user logged in only when both an access
+token and refresh token exist. The same stable bundle contains an unconditional
+test command that creates:
+
+- an unsigned JWT with issuer `cursor-smoke-test`, audience `cursor`, and
+  scope `smoke-test`;
+- the literal refresh token `fake-refresh-token-for-testing`.
+
+Impel reproduces that vendor-owned, non-secret identity in the tenant-only
+`state.vscdb` and also passes the JWT through Cursor's
+`--override-cursor-auth-token` process flag. It never asks for, reads, or
+stores a real Cursor credential. The source markers, storage keys, JWT contract,
+and command-line flags are part of the fail-closed vendor compatibility check.
+
+The fake identity unlocks the local Agent UI. Cursor-hosted account, model,
+analytics, and hosted-feature requests remain unauthenticated and cannot use
+the fake token for service access. The Impel PAT-derived tenant credential is
+given only to the bundled local provider:
+
+```text
+CURSOR_LOCAL_AGENT_BASE_URL=<gateway>/experimental/openai/v1
+CURSOR_LOCAL_AGENT_API_KEY=<tenant-scoped Impel credential>
+IMPEL_TENANT_ID=<tenant>
+```
+
+## Update and isolation contract
+
+For every prepare or open, Impel:
+
+1. Finds the installed stable `Cursor.app`.
+2. Verifies its complete Apple signature, Cursor bundle identifier, and vendor
+   Developer ID team.
+3. Reads the exact version and commit from `product.json`.
+4. Verifies every reviewed local-mode, authentication, provider-priority,
+   model-transport, and profile-import source contract.
+5. Verifies Cursor's extension-integrity table, then updates exactly the hashes
+   affected by the reviewed fixed-width patches.
+6. Recomputes Cursor's `product.json` checksum table after every reviewed
+   managed patch, so Cursor's own installation-integrity service verifies the
+   resulting managed bundle.
+7. Assigns a tenant-specific packaged application name and uses tenant-only
+   `HOME`, XDG, user-data, and extension roots. This isolates Cursor's
+   hardcoded `~/.cursor` agents, rules, plugins, worktrees, and logs in addition
+   to the normal VS Code profile state.
+8. Disables local-mode personal-data import so the managed app cannot inspect,
+   copy, or relaunch from the native Cursor profile.
+9. Clears inherited OpenAI, Anthropic, Google, AWS/Bedrock, Azure OpenAI,
+   Cursor, Node, Electron, and portable-profile overrides.
+10. Uses Cursor's built-in process-lifetime secret store. The managed runtime
+    has no real Cursor login or persistent provider key, while its gateway
+    bearer remains process-scoped in the launch environment.
+11. Re-signs every Electron process bundle with the reviewed entitlements and
+   verifies the complete managed copy.
+12. Atomically replaces the tenant generation only after every check passes.
+
+Tenant state lives below:
+
+```text
+~/.config/impel/apps/tenants/<tenant>/cursor/
+  runtime/current/Cursor.app
+  runtime/current/manifest.json
+  home/
+  user-data/
+  extensions/
+```
+
+The launcher rejects user-supplied `--user-data-dir`, `--extensions-dir`,
+and `--override-cursor-auth-token`. The native Cursor profile and the
+operator's `~/.cursor`, `~/.claude`, and `~/.codex` roots are never read or
+modified. The isolated `HOME` means shell, Git, and extension state that
+normally lives in a home directory must be configured separately for this
+tenant runtime.
+
+The managed copy disables self-updates. The signed native installation remains
+Cursor's update authority, and every `open` re-runs `prepare`, adopting a
+compatible stable vendor update immediately. If an update changes any reviewed
+contract, Impel preserves the previous generation and refuses the new build
+until its compatibility signatures and tests are reviewed.
+
+## Gateway contract
+
+The gateway must enable `IMPEL_EXPERIMENTAL_CROSS_APP_MODELS` and serve:
+
+```text
+GET  /experimental/openai/v1/models
+POST /experimental/openai/v1/chat/completions
+POST /experimental/openai/v1/responses
+```
+
+Cursor 3.12 initially submits Agent turns with its logical model `default`
+over Chat Completions, independently of the discovered catalog. The gateway
+maps that alias only on the experimental Cursor route to the exact registered
+Cursor default (`gpt-5.6-sol` today). Bifrost then performs its typed
+Chat-to-Responses conversion, including streaming response conversion, tools,
+reasoning, and multimodal messages. The converted request follows the normal
+pooled Codex path with `store:false`, tenant attribution, usage metering, and
+server-owned provider authentication.
+
+Explicit local-provider model requests can use Responses directly. The
+authenticated catalog is filtered by PAT scopes and live tenant pool readiness
+and advertises tools, streaming, reasoning, vision, context, modalities, and
+both protocol markers required by Cursor's bundled parser.
+
+Reasoning effort is a per-model, per-selection parameter rather than a global
+Cursor setting. The gateway catalog owns each model's allowed levels and
+default. Impel projects those values into Cursor's `Reasoning` selector, and the
+local Responses transport sends the selected value as `reasoning.effort`.
+Bifrost then converts that typed field for the selected Codex or Claude
+subscription provider. Models that advertise no reasoning levels receive no
+effort selector.
+
+## Battle-test result and parity boundary
+
+The gated packaged-GUI contract now proves all of the following against the
+real signed stable app and patched managed copy:
+
+- the native Cursor profile is unreadable and its sentinel remains unchanged;
+- the onboarding and hosted-login wall are absent;
+- the real `agent-exec` and local-agent runtime extensions activate;
+- authenticated `GET /models` reaches the loopback gateway;
+- the tenant catalog is reconciled into Cursor's named-model picker without
+  overwriting non-Impel model preferences;
+- a real Agent submission sends `model: "default"` to Chat Completions with
+  the tenant bearer;
+- the unique streamed gateway result is rendered in the Agent UI;
+- no personal provider credential or native profile is used.
+
+The direct runtime contract separately proves model discovery and a Responses
+stream with the intended model and bearer.
+
+The gateway conversion contract separately pins tool-call IDs across the next
+turn's tool result, fragmented parallel argument streams, reasoning deltas,
+`tool_calls` termination, vision input, and `store:false` after conversion.
+
+| Cursor surface | Managed local mode |
+| --- | --- |
+| Editor, terminal, source control, extensions | Retained with tenant-isolated state |
+| Agent chat, edits, terminal tools, MCP | Works through the Impel gateway |
+| Streaming, reasoning, vision, tool calls | Preserved by Cursor and Bifrost's typed conversion |
+| Model selection | Gateway owns `default`; concrete tenant models are projected into Cursor's named-model picker |
+| Tab completion | Unavailable; Cursor disables CPP/Tab in local mode |
+| Cloud Background Agents | Unavailable; hosted Cursor service |
+| Shared chats/canvases, Bugbot, code tour | Unavailable; hosted Cursor services |
+| Server-side repository indexing/search | Unavailable; hosted Cursor service |
+
+This provides direct Impel inference for the local Agent with normal Cursor
+editor updates. It cannot provide complete hosted-Cursor parity because Tab,
+cloud agents, collaboration, Bugbot, and hosted indexing use unpublished
+Cursor services rather than the bundled local-provider protocol. The app may
+still contact Cursor domains for updates, extensions, and unavailable hosted
+features; model inference is the gateway-owned boundary.
+
+The tenant gateway bearer is process-scoped because Cursor's current local
+provider contract resolves it from the launch environment. Treat extensions
+installed into this isolated Cursor profile as trusted: a same-user extension
+or process can inspect or reuse that gateway-only bearer. A short-lived,
+route-bound desktop capability would be a future hardening, but it is not part
+of the current PAT contract.
+
+## Validation
+
+The ordinary suite uses fake bundles and credentials. Validate the installed
+stable bundle and the direct local-provider transport with:
+
+```sh
+IMPEL_VALIDATE_INSTALLED_CURSOR_LOCAL=1 node --test --test-name-pattern='installed stable Cursor' test/cursor-local.test.js
+```
+
+The packaged GUI battle test uses only a disposable HOME, user-data directory,
+extension directory, workspace, process-lifetime secret store, loopback HTTP
+server, and loopback debugger:
+
+```sh
+IMPEL_VALIDATE_INSTALLED_CURSOR_GUI=1 node --test --test-name-pattern='managed Cursor GUI' test/cursor-local.test.js
+```
+
+Neither test reads or writes the operator's native Cursor profile or uses live
+provider credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.18.14",
+  "version": "0.18.15-beta.1",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {
@@ -12,15 +12,13 @@
   },
   "files": [
     "bin",
+    "docs/experimental-managed-cursor.md",
     "src",
     "README.md"
   ],
   "engines": {
     "node": ">=18.0.0"
   },
-  "scripts": {
-    "test": "node --test"
-  },
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public",
@@ -29,5 +27,8 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/UseImpel/impel-cli.git"
+  },
+  "scripts": {
+    "test": "node --test"
   }
-}
+}

package/src/commands/cursorExperimental.js

@@ -0,0 +1,192 @@
+import os from "node:os";
+
+import {
+  cursorLaunchSpec,
+  ensureCursorManagedAuthentication,
+  ensureCursorManagedModels,
+  launchManagedCursor,
+  managedCursorStatus,
+  prepareManagedCursor,
+  reusePreparedManagedCursor,
+} from "../cursorLocal.js";
+import { fetchHttp1 } from "../http1.js";
+import { loadConfig, normalizeGatewayUrl, redactSecretText, resolveDefaultGateway } from "../config.js";
+import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
+
+export const CURSOR_EXPERIMENT_HELP = `impel experimental cursor prepare|open|status
+
+Prepare, open, and inspect a tenant-isolated Cursor desktop runtime experiment.
+Agent inference uses the selected tenant's Impel gateway and an isolated,
+non-secret Cursor smoke identity. The signed stable Cursor.app in /Applications
+keeps updating normally; Impel mirrors and revalidates each compatible update
+without modifying the vendor app or the user's personal Cursor profile.
+
+Usage:
+  impel experimental cursor prepare
+  impel experimental cursor open [workspace-or-Cursor-args...]
+  impel experimental cursor status`;
+
+async function cursorGatewayCatalog(options, dependencies = {}) {
+  const fetchImpl = dependencies.fetch || fetchHttp1;
+  let response;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 7_000);
+    try {
+      response = await fetchImpl(
+        `${options.gatewayUrl}/experimental/openai/v1/models`,
+        {
+          headers: {
+            accept: "application/json",
+            authorization: `Bearer ${options.credential}`,
+          },
+          signal: controller.signal,
+        },
+      );
+      break;
+    } catch (error) {
+      if (error?.name === "AbortError" && attempt === 0) continue;
+      const detail = error?.name === "AbortError" ? "request timed out" : error?.message || error;
+      throw new Error(`could not read the Cursor model catalog: ${redactSecretText(detail)}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error(
+      `Cursor model catalog endpoint returned non-JSON (HTTP ${response.status}); deploy the matching impel-gateway Cursor catalog route`,
+    );
+  }
+  if (!response.ok) {
+    const detail = payload?.error?.message || payload?.error || `Cursor model catalog returned HTTP ${response.status}`;
+    throw new Error(redactSecretText(typeof detail === "string" ? detail : JSON.stringify(detail)));
+  }
+  if (payload?.org_id !== options.tenantId) {
+    throw new Error("Cursor model catalog tenant did not match the selected tenant");
+  }
+  if (!Array.isArray(payload.data) || payload.data.length === 0) {
+    throw new Error("Cursor model catalog returned no routable models");
+  }
+  const invalid = payload.data.find((model) => (
+    typeof model?.id !== "string"
+    || !Array.isArray(model.api_types)
+    || !model.api_types.includes("responses")
+    || model?.capabilities?.supports_tool_use !== true
+    || model?.capabilities?.supports_streaming !== true
+    || (
+      model?.capabilities?.supports_reasoning === true
+      && (
+        !Array.isArray(model.capabilities.reasoning_effort)
+        || model.capabilities.reasoning_effort.length === 0
+        || model.capabilities.reasoning_effort.some((effort) => typeof effort !== "string")
+        || (
+          model.capabilities.default_reasoning_effort !== undefined
+          && !model.capabilities.reasoning_effort.includes(model.capabilities.default_reasoning_effort)
+        )
+      )
+    )
+  ));
+  if (invalid) throw new Error("Cursor model catalog did not advertise the required Responses/tool contract");
+  return payload;
+}
+
+function statusLines(status, tenantId) {
+  const vendorLabel = status.vendor
+    ? `${status.vendor.version} (${status.vendor.commit.slice(0, 12)})`
+    : "incompatible";
+  const managedLabel = status.manifest?.vendor?.version || "not prepared";
+  return [
+    `Managed Cursor tenant: ${tenantId}`,
+    `Installed stable Cursor: ${vendorLabel}`,
+    `Managed runtime: ${managedLabel}`,
+    `Managed bundle contract: ${status.ready ? "ready" : "needs prepare"}`,
+    `Local Agent UI contract: ${status.ready ? "ready" : "needs prepare"}`,
+    ...(status.compatibilityError ? [`Compatibility: blocked — ${status.compatibilityError}`] : []),
+    ...(status.runtimeError ? [`Managed signature: invalid — ${status.runtimeError}`] : []),
+  ];
+}
+
+export async function cmdCursorExperimental(argv, dependencies = {}) {
+  const [action, ...args] = argv;
+  const log = dependencies.log || console.log;
+  if (action == null || action === "help") {
+    if (args.length) throw new Error("usage: impel experimental cursor prepare|open|status");
+    log(CURSOR_EXPERIMENT_HELP);
+    return;
+  }
+  if (!["prepare", "open", "status"].includes(action) || (action !== "open" && args.length)) {
+    throw new Error("usage: impel experimental cursor prepare|open|status");
+  }
+
+  const config = (dependencies.loadConfig || loadConfig)();
+  if (!config?.pat) throw new Error("run `impel setup` before preparing managed Cursor");
+  const selection = await (dependencies.ensureTenantSelection || ensureTenantSelection)(config, {
+    refresh: !Array.isArray(config.scopes),
+  });
+  assertProviderScopes(selection.scopes, ["claude", "codex"], { requireLive: true });
+  const tenantId = selection.tenantId;
+  const homeDir = dependencies.homeDir || os.homedir();
+  const gatewayUrl = normalizeGatewayUrl(config.gatewayUrl || resolveDefaultGateway());
+  const common = {
+    tenantId,
+    homeDir,
+    appRoot: dependencies.appRoot,
+    ...(dependencies.vendorPath ? { vendorPath: dependencies.vendorPath } : {}),
+  };
+  const credential = tenantCredential(config.pat, tenantId);
+
+  if (action === "status") {
+    const status = (dependencies.managedCursorStatus || managedCursorStatus)(common, dependencies);
+    for (const line of statusLines(status, tenantId)) log(line);
+    try {
+      const catalog = await cursorGatewayCatalog({ gatewayUrl, credential, tenantId }, dependencies);
+      log(`Gateway Cursor catalog: ready (${catalog.data.length} model${catalog.data.length === 1 ? "" : "s"})`);
+      return { ...status, gatewayReady: true, catalog };
+    } catch (error) {
+      const gatewayError = redactSecretText(error?.message || error);
+      log(`Gateway Cursor catalog: unavailable — ${gatewayError}`);
+      return { ...status, gatewayReady: false, gatewayError };
+    }
+  }
+
+  let prepared;
+  try {
+    prepared = (dependencies.prepareManagedCursor || prepareManagedCursor)(common, dependencies);
+  } catch (error) {
+    if (action !== "open") throw error;
+    prepared = (dependencies.reusePreparedManagedCursor || reusePreparedManagedCursor)(common, dependencies);
+    log(`Installed Cursor update was not imported; reusing the last verified managed runtime — ${redactSecretText(error?.message || error)}`);
+  }
+  const updateLabel = prepared.updated ? "Prepared" : "Reused";
+  log(`${updateLabel} managed Cursor ${prepared.source.version} for tenant ${tenantId}.`);
+  if (action === "prepare") return prepared;
+  const catalog = await cursorGatewayCatalog({ gatewayUrl, credential, tenantId }, dependencies);
+  const managedModels = (dependencies.ensureCursorManagedModels || ensureCursorManagedModels)(
+    prepared.paths.userData,
+    catalog.data,
+    `${gatewayUrl}/experimental/openai/v1`,
+    dependencies,
+  );
+  const authentication = (dependencies.ensureCursorManagedAuthentication || ensureCursorManagedAuthentication)(
+    prepared.paths.userData,
+    dependencies,
+  );
+  const spec = (dependencies.cursorLaunchSpec || cursorLaunchSpec)({
+    paths: prepared.paths,
+    gatewayUrl,
+    credential,
+    tenantId,
+    cursorAuthToken: authentication.token,
+    argv: args,
+    environment: dependencies.environment || process.env,
+  });
+  await (dependencies.launchManagedCursor || launchManagedCursor)(spec, dependencies);
+  log(`Opened managed Cursor for tenant ${tenantId} with ${catalog.data.length} gateway model${catalog.data.length === 1 ? "" : "s"}.`);
+  return { ...prepared, catalog, managedModels, launched: true };
+
+}
+
+export { cursorGatewayCatalog };

package/src/commands/experimental.js

@@ -1,5 +1,6 @@
 import { crossAppModelsEnabled, loadConfig, saveConfig } from "../config.js";
 import { assertProviderScopes, ensureTenantSelection } from "../tenants.js";
+import { cmdCursorExperimental, CURSOR_EXPERIMENT_HELP } from "./cursorExperimental.js";
 
 const HELP = `impel experimental cross-app-models enable|disable|status
 
@@ -10,7 +11,9 @@ It does not modify native profiles or support the consumer ChatGPT app
 (com.openai.chat).
 
 Run \`impel app refresh all\` to refresh desktop configs. Reopen an Impel app
-or isolated CLI to apply the experiment.`;
+or isolated CLI to apply the experiment.
+
+${CURSOR_EXPERIMENT_HELP}`;
 
 export async function cmdExperimental(argv, dependencies = {}) {
   const read = dependencies.loadConfig || loadConfig;
@@ -23,8 +26,11 @@ export async function cmdExperimental(argv, dependencies = {}) {
     log(HELP);
     return;
   }
+  if (experiment === "cursor") {
+    return cmdCursorExperimental([action, ...extra], dependencies);
+  }
   if (experiment !== "cross-app-models" || !["enable", "disable", "status"].includes(action) || extra.length > 0) {
-    throw new Error("usage: impel experimental cross-app-models enable|disable|status");
+    throw new Error("usage: impel experimental cross-app-models enable|disable|status | impel experimental cursor prepare|open|status");
   }
 
   const config = read();