impel-cli 0.16.4 → 0.16.5

package/README.md

@@ -25,6 +25,32 @@ of the protected Store directory and launches it with tenant-specific Codex and
 browser profiles. Each approach keeps the user's normal app profile and
 signed-in account untouched.
 
+Every Impel-managed Claude Code, Codex CLI, Claude Desktop, and ChatGPT/Codex
+Desktop profile also installs tenant-scoped lifecycle hooks for cloud session
+persistence. Hook input is first written to a private local outbox, so an
+offline network, interrupted hook, force-quit, or client restart cannot make a
+provider turn fail. The next hook invocation retries any pending batches,
+including batches left by an older session. Remote payloads are stored as
+independent zstd frames by `impel-sessions`; the local collector sends bounded
+newline-complete transcript deltas and a compact lifecycle ledger. Pending data
+is capped at 256 MiB or 2,048 batches per session by default; corrupt or
+permanently invalid batches are quarantined so they cannot block later data.
+Set `IMPEL_SESSIONS_MAX_OUTBOX_BYTES` or `IMPEL_SESSIONS_MAX_OUTBOX_BATCHES` to
+lower those local limits.
+
+The service attributes each session to the PAT-resolved user and selected
+tenant and records the provider, CLI/desktop surface, provider session ID, and
+repository metadata. Set `IMPEL_TASK_ID` before launching a client to link new
+sessions explicitly to an Impel task for cross-device discovery. The collector
+never writes the configured PAT into hook configuration, and it redacts Impel
+PAT/tenant credentials found in hook input or transcript content before
+spooling. Task linkage is retried independently and cannot block payload
+persistence when the current PAT lacks the `tasks` scope.
+
+Codex hook trust is pinned to the exact generated handler and its array index.
+If you manually reorder the managed group in `hooks.json`, rerun `impel setup`,
+`impel app update`, or relaunch the isolated CLI to regenerate the trust entry.
+
 ## Gateway-only vendor package
 
 White-labelled gateway launchers import the deliberately narrow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.16.4",
+  "version": "0.16.5",
   "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
   "type": "module",
   "bin": {

package/src/apps.js

@@ -12,6 +12,7 @@ import {
 import { normalizeTenantId } from "./tenants.js";
 import { impelCliInvocation } from "./selfInvocation.js";
 import { crossAppModelsEnabled, redactSecretText } from "./config.js";
+import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
 import { ADHOC_IDENTITY, codesignIdentityArgs, desiredSigningMode, resolveSigningIdentity } from "./codesign.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
 
@@ -163,7 +164,7 @@ export function managedAppIdentity(target, tenantId = null, tenantName = null) {
 
 // Bump when the written config/manifest schema changes; a mismatch forces the
 // slow open path (and thus a full config rewrite) after a CLI update.
-export const CURRENT_CONFIG_VERSION = 15;
+export const CURRENT_CONFIG_VERSION = 16;
 
 // Identifies the bundle-BUILDING logic — the asar patches, plist rewrites,
 // helper rebranding, and signing. A vendored bundle is rebuilt only when this
@@ -617,8 +618,12 @@ export function installManagedAppFiles({
       writeClaudeDefaultApp(paths);
       writeClaudeCodeSettings(paths);
       writeClaudeConfig(paths, config, models);
+      ensureClaudeSessionHooks(paths.claude.userData, config.tenantId, "claude_desktop");
+    }
+    else {
+      writeChatGPTConfig(paths, config, models, vendorCodexModels, chatgptInvocations);
+      ensureCodexSessionHooks(paths.chatgpt.codexHome, config.tenantId, "codex_desktop");
     }
-    else writeChatGPTConfig(paths, config, models, vendorCodexModels, chatgptInvocations);
     // Non-bundle targets are the background-refresh / fast-open path: configs,
     // token helper, catalog, and manifest only. Bundle swaps require the app
     // to be closed (see quitBlockingApps), so those paths never attempt one.
@@ -1024,6 +1029,7 @@ function writeChatGPTConfig(paths, config, models, vendorCodexModels, invocation
   const managedToml = [
     CHATGPT_CONFIG_START,
     "# Managed by `impel app update`. This profile is isolated from ~/.codex.",
+    "# Impel session-hook trust is pinned separately by exact handler hash.",
     `model = ${tomlString(selectedModel.slug)}`,
     'model_provider = "impel"',
     `chatgpt_base_url = ${tomlString(`${config.gatewayUrl}/chatgpt_passthrough/backend-api`)}`,

package/src/cli.js

@@ -15,6 +15,7 @@ import { cmdAgents } from "./commands/agents.js";
 import { cmdTenant } from "./commands/tenant.js";
 import { cmdDoctor } from "./commands/doctor.js";
 import { cmdSetup } from "./commands/setup.js";
+import { cmdSessions } from "./commands/sessions.js";
 import { cmdUpdate } from "./commands/update.js";
 import { cmdExperimental } from "./commands/experimental.js";
 
@@ -121,6 +122,10 @@ export async function main(argv) {
     case "mcp":
       return cmdMcp(rest);
 
+    // Hidden transport used by managed Claude/Codex lifecycle hooks.
+    case "sessions":
+      return cmdSessions(rest);
+
     case "claude":
     case "codex":
       return cmdLaunch(cmd, rest);

package/src/cliProfiles.js

@@ -12,6 +12,7 @@ import { CONFIG_DIR } from "./config.js";
 import { normalizeTenantId } from "./tenants.js";
 import { impelCliInvocation, impelMcpInvocation } from "./selfInvocation.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
+import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
 
 export const IMPEL_CLI_PROFILES_DIR = path.join(CONFIG_DIR, "cli");
 
@@ -131,6 +132,7 @@ export function ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels
 
   writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   writePrivateFile(userConfigPath, `${JSON.stringify(userConfig, null, 2)}\n`);
+  ensureClaudeSessionHooks(configDir, tenantId, "claude_cli");
 
   return { configDir, settingsPath, userConfigPath };
 }
@@ -203,9 +205,10 @@ export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
 
   const { preamble, rest } = splitTomlPreamble(withoutManagedBlock);
   const providerLine = 'model_provider = "impel"';
-  const nextPreamble = CODEX_PROVIDER_LINE_RE.test(preamble)
+  let nextPreamble = CODEX_PROVIDER_LINE_RE.test(preamble)
     ? preamble.replace(CODEX_PROVIDER_LINE_RE, providerLine)
     : `${preamble.trimEnd()}${preamble.trim() ? "\n" : ""}${providerLine}\n`;
+  nextPreamble = nextPreamble.replace(/^bypass_hook_trust[ \t]*=[ \t]*(?:true|false)[ \t]*\n?/gm, "");
   const restText = rest.trim();
   const next = [nextPreamble.trimEnd(), codexManagedBlock(gatewayUrl, tenantId), restText]
     .filter(Boolean)
@@ -213,6 +216,7 @@ export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
     .concat("\n");
 
   writePrivateFile(configPath, hardenManagedCodexToml(next, configPath));
+  ensureCodexSessionHooks(codexHome, tenantId, "codex_cli");
   secureManagedCodexHome(codexHome);
   return { codexHome, configPath };
 }

package/src/commands/sessions.js

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+
+import { parseFlags } from "../args.js";
+import { collectSessionHook, flushCollectedSession, readHookInput, sessionOutboxStatus } from "../sessionCollector.js";
+import { loadConfig, redactSecretText } from "../config.js";
+import { impelCliInvocation } from "../selfInvocation.js";
+
+const SPEC = {
+  provider: { type: "string" },
+  surface: { type: "string" },
+  tenant: { type: "string" },
+  session: { type: "string" },
+  "impel-managed-session-hook-v1": { type: "boolean" },
+};
+
+function startDetachedFlush({ provider, tenant, session }) {
+  const invocation = impelCliInvocation([
+    "sessions",
+    "flush",
+    "--provider",
+    provider,
+    "--tenant",
+    tenant,
+    "--session",
+    session,
+    "--impel-managed-session-hook-v1",
+  ]);
+  const child = spawn(invocation.command, invocation.args, {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, IMPEL_SESSIONS_FLUSH_CHILD: "1" },
+    windowsHide: true,
+  });
+  child.once("error", () => {});
+  child.unref();
+}
+
+export async function cmdSessions(argv) {
+  const [action, ...rest] = argv;
+  if (action === "hook") {
+    try {
+      const { flags, positionals } = parseFlags(rest, SPEC);
+      if (positionals.length > 0) throw new Error("unexpected positional arguments");
+      const input = await readHookInput();
+      let config = null;
+      try {
+        config = loadConfig();
+      } catch {
+        // Capture remains available even while the user's config needs repair.
+      }
+      await collectSessionHook({
+        provider: flags.provider,
+        surface: flags.surface,
+        tenantId: flags.tenant,
+        input,
+        config,
+        flush: false,
+      });
+      if (config && (config.tenantId === flags.tenant || process.env.IMPEL_SESSIONS_DEV_ORG_ID)) {
+        startDetachedFlush({
+          provider: flags.provider,
+          tenant: flags.tenant,
+          session: String(input.session_id || ""),
+        });
+      }
+    } catch (error) {
+      // Session persistence is observational. A collector outage must never
+      // block a model turn or change a provider hook's decision semantics.
+      if (process.env.IMPEL_SESSIONS_DEBUG === "1") {
+        console.error(`impel sessions hook: ${redactSecretText(error?.message || error)}`);
+      }
+    }
+    return;
+  }
+  const { flags, positionals } = parseFlags(rest, SPEC);
+  if (positionals.length > 0) {
+    console.error("impel sessions: unexpected positional arguments");
+    process.exitCode = 1;
+    return;
+  }
+  const config = loadConfig();
+  if (action === "flush") {
+    if (!flags.provider || !flags.session || !flags.tenant) return;
+    if (!["claude_code", "codex"].includes(flags.provider)) return;
+    if (!config || flags.tenant !== config.tenantId && !process.env.IMPEL_SESSIONS_DEV_ORG_ID) return;
+    const deadline = Date.now() + 90_000;
+    while (Date.now() < deadline) {
+      const result = await flushCollectedSession({
+        tenantId: flags.tenant,
+        provider: flags.provider,
+        sessionKey: flags.session,
+        config,
+      });
+      if (result.pending === 0) break;
+      await new Promise((resolve) => setTimeout(resolve, result.error || result.busy ? 1000 : 250));
+    }
+    return;
+  }
+  if (action === "status") {
+    if (!flags.provider || !flags.session || !flags.tenant) {
+      console.error("impel sessions status requires --provider, --session, and --tenant");
+      process.exitCode = 1;
+      return;
+    }
+    console.log(JSON.stringify(sessionOutboxStatus({
+      tenantId: flags.tenant,
+      provider: flags.provider,
+      sessionKey: flags.session,
+    }), null, 2));
+    return;
+  }
+  console.error("impel sessions: use `hook` (managed internally) or `status`");
+  process.exitCode = 1;
+}

package/src/config.js

@@ -89,11 +89,16 @@ const PAT_RE = /impel_pat_[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?/gu;
 const ANSI_ESCAPE_RE = /\u001B(?:\][^\u0007\u001B]*(?:\u0007|\u001B\\)|\[[0-?]*[ -/]*[@-~]|[@-_])/gu;
 const TERMINAL_CONTROL_RE = /[\u0000-\u001F\u007F-\u009F]/gu;
 
-/** Remove credentials and terminal control sequences from untrusted text. */
-export function redactSecretText(value) {
+/** Redact Impel bearer credentials without changing JSON/NDJSON whitespace. */
+export function redactCredentialText(value) {
   return String(value ?? "")
     .replace(TENANT_CREDENTIAL_RE, "[REDACTED IMPEL CREDENTIAL]")
-    .replace(PAT_RE, "[REDACTED IMPEL CREDENTIAL]")
+    .replace(PAT_RE, "[REDACTED IMPEL CREDENTIAL]");
+}
+
+/** Remove credentials and terminal control sequences from untrusted text. */
+export function redactSecretText(value) {
+  return redactCredentialText(value)
     .replace(ANSI_ESCAPE_RE, "")
     .replace(TERMINAL_CONTROL_RE, " ");
 }