impel-cli 0.18.15-beta.9 → 0.18.15

package/README.md

@@ -100,50 +100,6 @@ 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.13.25 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:
@@ -223,11 +179,6 @@ impel update --no-recovery    # disable recovery for this run
 schema verified by that CLI. It does not mean cloning an untested moving vendor
 release.
 
-Stable installations follow npm's `latest` tag. Prerelease installations made
-from `impel-cli@next` remain on the `next` channel during `impel update`. If npm
-metadata is temporarily unavailable, update preserves the installed CLI build
-and continues tenant reconciliation without attempting a downgrade.
-
 ## Status and diagnosis
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.18.15-beta.9",
+  "version": "0.18.15",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {
@@ -12,7 +12,6 @@
   },
   "files": [
     "bin",
-    "docs/experimental-managed-cursor.md",
     "src",
     "README.md"
   ],

package/src/agents.js

@@ -21,6 +21,7 @@ export const NATIVE_AGENT_LIST_TOOL = "impel_specialists-list_native_agents";
 export const NATIVE_AGENT_START_TOOL = "impel_specialists-start_native_agent_run";
 export const NATIVE_AGENT_READ_TOOL = "impel_specialists-read_native_agent_run";
 export const MANAGED_AGENT_MCP_SERVER = "impel_agent";
+export const MANAGED_AGENT_MANIFEST_VERSION = 4;
 
 const NATIVE_AGENT_TOOL_NAMES = [
   NATIVE_AGENT_LIST_TOOL,
@@ -320,7 +321,7 @@ function generatedClientAgentNames(client, agents) {
   });
 }
 
-function adapterInstructions(tenantId, agent) {
+function claudeAdapterInstructions(tenantId, agent) {
   const toolName = nativeToolName;
   const contextRequirement = agent.requiredContext.length
     ? ` Required context keys are ${JSON.stringify(agent.requiredContext)}; if any are absent, ask for them before starting the run.`
@@ -333,7 +334,7 @@ function adapterInstructions(tenantId, agent) {
     `Do not perform the assigned task yourself and do not delegate to any other agent.`,
     `First call ${toolName(NATIVE_AGENT_LIST_TOOL)} and verify that the exact agentId is still available with sideEffects ${JSON.stringify(agent.sideEffects)}. If it is unavailable or its policy excludes the request, stop with that explicit error.`,
     sideEffectInstruction,
-    `Call ${toolName(NATIVE_AGENT_START_TOOL)} exactly once with agentId ${JSON.stringify(agent.agentId)}, scopeParam ${JSON.stringify(agent.scopeParam)}, task set to the complete assigned task, context and contextKeys containing all supplied context, confirmedSideEffects as directed above, and one stable idempotencyKey that you reuse for this logical task.${contextRequirement}`,
+    `Call ${toolName(NATIVE_AGENT_START_TOOL)} exactly once with agentId ${JSON.stringify(agent.agentId)}, scopeParam ${JSON.stringify(agent.scopeParam)}, task set to the complete assigned task, optional context set to one string containing all supplied context (omit it when no context was supplied), contextKeys naming the context fields present in that string, confirmedSideEffects as directed above, and one stable idempotencyKey that you reuse for this logical task.${contextRequirement}`,
     `Then call ${toolName(NATIVE_AGENT_READ_TOOL)} with the returned runId and waitSeconds 20 until the run reaches a terminal state.`,
     `When it succeeds, return result.finalText faithfully as the answer. When it fails, return the durable runId, preserved output, and error. Never invent or independently synthesize a replacement result.`,
   ].join(" ");
@@ -343,6 +344,170 @@ function nativeToolName(toolName) {
   return `mcp__${MANAGED_AGENT_MCP_SERVER}__${toolName}`;
 }
 
+const CODEX_TASK_PLACEHOLDER = "__IMPEL_COMPLETE_ASSIGNED_TASK_JSON__";
+const CODEX_CONTEXT_PLACEHOLDER = "__IMPEL_OPTIONAL_CONTEXT_STRING_OR_NULL_JSON__";
+const CODEX_CONTEXT_KEYS_PLACEHOLDER = "__IMPEL_SUPPLIED_CONTEXT_KEYS_JSON__";
+const CODEX_IDEMPOTENCY_KEY_PLACEHOLDER = "__IMPEL_LOGICAL_INVOCATION_IDEMPOTENCY_KEY_JSON__";
+
+export function renderCodexAdapterOrchestration(tenantId, agent) {
+  const expectedTenantId = normalizeTenantId(tenantId);
+  const nestedToolName = (toolName) => nativeToolName(toolName).replaceAll("-", "_");
+  const listTool = nestedToolName(NATIVE_AGENT_LIST_TOOL);
+  const startTool = nestedToolName(NATIVE_AGENT_START_TOOL);
+  const readTool = nestedToolName(NATIVE_AGENT_READ_TOOL);
+  return [
+    '// @exec: {"yield_time_ms": 30000, "max_output_tokens": 30000}',
+    `const assignedTask = ${CODEX_TASK_PLACEHOLDER};`,
+    `const suppliedContext = ${CODEX_CONTEXT_PLACEHOLDER};`,
+    `const suppliedContextKeys = ${CODEX_CONTEXT_KEYS_PLACEHOLDER};`,
+    `const idempotencyKey = ${CODEX_IDEMPOTENCY_KEY_PLACEHOLDER};`,
+    `const expectedTenantId = ${JSON.stringify(expectedTenantId)};`,
+    `const expectedAgent = ${JSON.stringify(agent)};`,
+    "const waitSeconds = 20; // Compatible fallback until the bound server advertises a larger ceiling.",
+    `const listToolName = ${JSON.stringify(listTool)};`,
+    `const startToolName = ${JSON.stringify(startTool)};`,
+    `const readToolName = ${JSON.stringify(readTool)};`,
+    "",
+    "function stableValue(value) {",
+    "  if (Array.isArray(value)) return value.map(stableValue);",
+    '  if (!value || typeof value !== "object") return value;',
+    "  const result = {};",
+    "  for (const key of Object.keys(value).sort()) result[key] = stableValue(value[key]);",
+    "  return result;",
+    "}",
+    "",
+    "function contentText(response) {",
+    '  return response?.content?.find((item) => item?.type === "text" && typeof item.text === "string")?.text;',
+    "}",
+    "",
+    "function toolPayload(response, label) {",
+    '  if (!response || typeof response !== "object") throw new Error(label + " returned no result");',
+    '  if (response.isError) throw new Error(contentText(response) || label + " failed");',
+    '  if (response.structuredContent && typeof response.structuredContent === "object") return response.structuredContent;',
+    "  const serialized = contentText(response);",
+    "  if (serialized !== undefined) {",
+    "    try {",
+    "      return JSON.parse(serialized);",
+    "    } catch {",
+    '      throw new Error(label + " returned invalid JSON");',
+    "    }",
+    "  }",
+    "  return response;",
+    "}",
+    "",
+    "function preservedOutput(run) {",
+    '  if (run && Object.prototype.hasOwnProperty.call(run, "output")) return run.output;',
+    '  if (run && Object.prototype.hasOwnProperty.call(run, "result")) return run.result;',
+    "  return null;",
+    "}",
+    "",
+    "function errorValue(error, fallback) {",
+    "  if (error === undefined || error === null) return fallback;",
+    '  if (error instanceof Error) return error.message;',
+    "  return error;",
+    "}",
+    "",
+    "async function orchestrate() {",
+    "  let runId = null;",
+    "  let latestRun = null;",
+    "  try {",
+    '    if (typeof assignedTask !== "string" || !assignedTask.trim()) throw new Error("the complete assigned task is required");',
+    '    if (suppliedContext !== null && typeof suppliedContext !== "string") throw new Error("supplied context must be a string or null");',
+    '    if (expectedAgent.requiredContext.length && (typeof suppliedContext !== "string" || !suppliedContext.trim())) {',
+    '      throw new Error("nonblank supplied context is required for required context keys");',
+    "    }",
+    '    if (!Array.isArray(suppliedContextKeys)) throw new Error("supplied context keys must be an array");',
+    '    if (typeof idempotencyKey !== "string" || !/^[A-Za-z0-9._:-]{16,160}$/u.test(idempotencyKey)) {',
+    '      throw new Error("a unique stable logical-invocation idempotencyKey is required");',
+    "    }",
+    "    const missingContext = expectedAgent.requiredContext.filter((key) =>",
+    "      !suppliedContextKeys.includes(key)",
+    "    );",
+    '    if (missingContext.length) throw new Error("missing required context: " + missingContext.join(", "));',
+    "",
+    "    const catalog = toolPayload(await tools[listToolName]({}), \"native-agent catalog\");",
+    '    if (catalog.orgId !== expectedTenantId) throw new Error("native-agent catalog tenant mismatch");',
+    '    if (!Array.isArray(catalog.agents)) throw new Error("native-agent catalog returned no agents");',
+    "    const matches = catalog.agents.filter((candidate) =>",
+    "      candidate?.agentId === expectedAgent.agentId && candidate?.scopeParam === expectedAgent.scopeParam",
+    "    );",
+    '    if (matches.length !== 1) throw new Error("exact native-agent binding is unavailable");',
+    "    const actualAgent = {};",
+    "    for (const key of Object.keys(expectedAgent)) actualAgent[key] = matches[0][key];",
+    "    if (JSON.stringify(stableValue(actualAgent)) !== JSON.stringify(stableValue(expectedAgent))) {",
+    '      throw new Error("native-agent catalog policy mismatch");',
+    "    }",
+    "",
+    "    const startArguments = {",
+    "      agentId: expectedAgent.agentId,",
+    "      scopeParam: expectedAgent.scopeParam,",
+    "      task: assignedTask,",
+    "      contextKeys: suppliedContextKeys,",
+    "      idempotencyKey,",
+    "    };",
+    "    if (suppliedContext !== null) startArguments.context = suppliedContext;",
+    '    if (expectedAgent.sideEffects === "writes") startArguments.confirmedSideEffects = true;',
+    "    latestRun = toolPayload(await tools[startToolName](startArguments), \"native-agent start\");",
+    '    if (typeof latestRun.runId !== "string" || !latestRun.runId) throw new Error("native-agent start returned no runId");',
+    "    runId = latestRun.runId;",
+    "",
+    "    for (;;) {",
+    "      const observed = toolPayload(",
+    "        await tools[readToolName]({ runId, waitSeconds }),",
+    '        "native-agent read",',
+    "      );",
+    '      if (observed.runId !== undefined && observed.runId !== runId) throw new Error("native-agent read returned a different runId");',
+    "      latestRun = observed;",
+    '      if (observed.status === "succeeded") {',
+    '        const finalText = observed.result?.finalText;',
+    '        if (typeof finalText !== "string") throw new Error("succeeded native-agent run returned no finalText");',
+    "        text(finalText);",
+    "        return;",
+    "      }",
+    '      if (observed.status === "failed") {',
+    "        text(JSON.stringify({",
+    "          runId,",
+    "          output: preservedOutput(observed),",
+    '          error: errorValue(observed.error, "native-agent run failed"),',
+    "        }));",
+    "        return;",
+    "      }",
+    "    }",
+    "  } catch (error) {",
+    "    text(JSON.stringify({",
+    "      runId,",
+    "      output: preservedOutput(latestRun),",
+    '      error: errorValue(error, "native-agent adapter failed"),',
+    "    }));",
+    "  }",
+    "}",
+    "",
+    "await orchestrate();",
+  ].join("\n");
+}
+
+function codexAdapterInstructions(tenantId, agent) {
+  const contextRequirement = agent.requiredContext.length
+    ? ` Required context keys are ${JSON.stringify(agent.requiredContext)}; if any are absent, ask for them before starting the run.`
+    : "";
+  const sideEffectInstruction = agent.sideEffects === "writes"
+    ? `The catalog declares that this agent writes user or workspace data. Use this adapter only when the user explicitly selected this exact agent for the current request; that explicit selection is the required side-effect confirmation. If the agent was chosen automatically or the selection is ambiguous, do not run the orchestration and ask the user to select this exact agent explicitly.`
+    : `The catalog declares that this agent is read-only; the orchestration omits confirmedSideEffects.`;
+  const source = renderCodexAdapterOrchestration(tenantId, agent);
+  return [
+    `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
+    `Callers must spawn this explicit custom Codex agent with fork_turns="none" and must relay your result verbatim; this is caller guidance and cannot enforce host spawn behavior.`,
+    `Do not perform the assigned task yourself, do not delegate to any other agent, and do not independently synthesize or rewrite the result.`,
+    `Confirm that the assigned request fits the cataloged capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)} before starting.${contextRequirement}`,
+    sideEffectInstruction,
+    `Invoke functions.exec exactly once for the orchestration below. Do not call the MCP tools directly or select a separate MCP call for any poll. Replace ${CODEX_TASK_PLACEHOLDER} with a JSON string literal for the complete assigned task. Replace ${CODEX_CONTEXT_PLACEHOLDER} with one JSON string literal containing all supplied caller context, or with null when no context was supplied; never use an object or array. Replace ${CODEX_CONTEXT_KEYS_PLACEHOLDER} with a JSON array naming the context fields present in that string, or [] when context is absent. Replace ${CODEX_IDEMPOTENCY_KEY_PLACEHOLDER} with one new opaque idempotency key for this logical invocation: choose it exactly once, reuse it unchanged for any retry of this invocation, and never reuse it for a separate request even when task and context are identical. Then pass the raw JavaScript without Markdown fences.`,
+    `The JavaScript validates the exact tenant, agent binding, and catalog policy; passes the one stable logical-invocation idempotencyKey; starts exactly once; and polls deterministically with the compatible 20-second server wait until status is succeeded or failed. If functions.exec yields a running cell, use functions.wait with max_tokens 30000 only to resume that same orchestration; never start another orchestration or poll the MCP tool yourself.`,
+    `After the orchestration completes, return its single text output verbatim with no preface, rewriting, Markdown changes, or independent synthesis. A successful output is result.finalText exactly. A failure output preserves the durable runId, output, and error.`,
+    "",
+    source,
+  ].join("\n\n");
+}
+
 function renderClaudeAgent({ tenantId, agent, name, invocation }) {
   const description = `Explicitly runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
   const lines = [
@@ -362,14 +527,14 @@ function renderClaudeAgent({ tenantId, agent, name, invocation }) {
     ...Object.entries(invocation.env || {}).map(([key, value]) => `        ${key}: ${JSON.stringify(value)}`),
     "---",
     "",
-    adapterInstructions(tenantId, agent),
+    claudeAdapterInstructions(tenantId, agent),
     "",
   ];
   return lines.join("\n");
 }
 
 function renderCodexAgent({ tenantId, agent, name, invocation }) {
-  const description = `Explicitly runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
+  const description = `Explicit custom agent: callers must use fork_turns="none" and relay its result verbatim. Runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
   const envEntries = Object.entries(invocation.env || {})
     .map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`)
     .join(", ");
@@ -377,7 +542,7 @@ function renderCodexAgent({ tenantId, agent, name, invocation }) {
     `name = ${JSON.stringify(name)}`,
     `description = ${JSON.stringify(description)}`,
     'sandbox_mode = "read-only"',
-    `developer_instructions = ${JSON.stringify(adapterInstructions(tenantId, agent))}`,
+    `developer_instructions = ${JSON.stringify(codexAdapterInstructions(tenantId, agent))}`,
     "",
     `[mcp_servers.${MANAGED_AGENT_MCP_SERVER}]`,
     `command = ${JSON.stringify(invocation.command)}`,
@@ -440,7 +605,7 @@ function readManifest(manifestPath) {
 
 function profileIsFresh(profile, tenantId, now, ttlMs) {
   const manifest = readManifest(path.join(profile.root, "agents", MANAGED_AGENT_DIRECTORY, MANAGED_AGENT_MANIFEST));
-  if (!manifest || manifest.version !== 3 || manifest.tenantId !== tenantId) return false;
+  if (!manifest || manifest.version !== MANAGED_AGENT_MANIFEST_VERSION || manifest.tenantId !== tenantId) return false;
   const syncedAt = Date.parse(manifest.syncedAt || "");
   if (!Number.isFinite(syncedAt) || now - syncedAt >= ttlMs) return false;
   return manifest.files.every((fileName) =>
@@ -463,7 +628,7 @@ export function syncAgentProfile({ client, root, label, tenantId, agents, now =
   const prior = readManifest(manifestPath);
   const rendered = renderManagedAgents(client, tenantId, agents);
   const priorFiles = new Set(prior?.files || []);
-  const priorUsesDiscoveryRoot = prior?.version === 2 || prior?.version === 3;
+  const priorUsesDiscoveryRoot = [2, 3, MANAGED_AGENT_MANIFEST_VERSION].includes(prior?.version);
 
   // Native clients discover standalone definitions directly under `agents/`.
   // Preflight every destination before writing so an unmanaged file with the
@@ -505,7 +670,7 @@ export function syncAgentProfile({ client, root, label, tenantId, agents, now =
     }
   }
   atomicPrivateWrite(manifestPath, `${JSON.stringify({
-    version: 3,
+    version: MANAGED_AGENT_MANIFEST_VERSION,
     tenantId,
     client,
     syncedAt: new Date(now).toISOString(),