@byok-sdk/keys 0.4.3 → 0.6.0

package/README.md

@@ -1,5 +1,41 @@
 # @byok-sdk/keys
 
+Pi launcher configuration is explicit, from the published 0.5.0 onward.
+Set `pi_model` on `ProviderRegistry.configure` for profiles used by Pi:
+
+```ts
+const pi_model = {
+  contextWindow: 1_000_000,
+  maxTokens: 131_072,
+  reasoning: true,
+  thinkingLevel: 'low',
+  thinkingLevelMap: {
+    off: null, minimal: null, low: 'low', medium: null,
+    high: 'high', xhigh: null, max: 'max',
+  },
+  compat: {
+    supportsStore: false, supportsDeveloperRole: false,
+    supportsReasoningEffort: true, supportsUsageInStreaming: true,
+    maxTokensField: 'max_tokens', thinkingFormat: 'zai', zaiToolStream: true,
+  },
+} satisfies PiModelConfig;
+```
+
+These illustrate declared GLM-5.3-Flash/Pi model settings, not Host input budgets
+or automatic defaults. Import `PiModelConfig` from this package. The bounded
+`PiModelConfigSchema` rejects unknown fields, incomplete level maps and
+unsupported selected levels; it accepts no identity, URL, header or secret.
+Use the exact provider's authoritative configuration. Missing `pi_model`
+permits direct provider transports but rejects Pi admission and launch.
+Configuration changes alter the profile hash and registry revision, fencing
+stale tasks before credential access. The launcher projects the selected
+thinking level through its own argv, not delegated overrides.
+
+The SQLite profile schema changes in this candidate. Existing stores are
+rejected and preserved: explicitly provision a separate current-schema store
+after reviewing the old configuration. Do not delete an old store or infer its
+missing model settings. No live-store conversion is performed by the SDK.
+
 Key-based BYOK: a validated provider profile, credential-backed auth headers, and
 direct transports to OpenAI-compatible and Anthropic providers.
 

package/dist/bin/pi-provider-launcher.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
+import path2, { dirname, isAbsolute } from 'path';
 import { spawn } from 'child_process';
-import { promises, mkdirSync, existsSync, chmodSync } from 'fs';
-import os from 'os';
-import path2, { dirname } from 'path';
 import { z } from 'zod';
 import { createHash } from 'crypto';
+import { promises, mkdirSync, existsSync, chmodSync } from 'fs';
+import { parseImplementationSpawnBinding, assertImplementationSpawnBinding, projectKeysPiInheritedEnvironment } from '@byok-sdk/implementation-identity';
 import { createRequire } from 'module';
 
 // src/errors.ts
@@ -193,6 +193,54 @@ function isPrivateNetworkLiteral(hostname) {
   }
   return parts[0] === 10 || parts[0] === 127 || parts[0] === 169 && parts[1] === 254 || parts[0] === 172 && (parts[1] ?? 0) >= 16 && (parts[1] ?? 0) <= 31 || parts[0] === 192 && parts[1] === 168;
 }
+var PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+var effort = z.string().min(1).max(64).regex(/^[a-zA-Z0-9_-]+$/u).nullable();
+var PiModelConfigSchema = z.object({
+  contextWindow: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  maxTokens: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  reasoning: z.boolean(),
+  thinkingLevel: z.enum(PI_THINKING_LEVELS),
+  thinkingLevelMap: z.object({
+    off: effort,
+    minimal: effort,
+    low: effort,
+    medium: effort,
+    high: effort,
+    xhigh: effort,
+    max: effort
+  }).strict(),
+  compat: z.object({
+    supportsStore: z.boolean().optional(),
+    supportsDeveloperRole: z.boolean().optional(),
+    supportsReasoningEffort: z.boolean().optional(),
+    supportsUsageInStreaming: z.boolean().optional(),
+    maxTokensField: z.enum(["max_completion_tokens", "max_tokens"]).optional(),
+    thinkingFormat: z.enum([
+      "openai",
+      "openrouter",
+      "deepseek",
+      "together",
+      "baseten",
+      "zai",
+      "qwen",
+      "chat-template",
+      "qwen-chat-template",
+      "string-thinking",
+      "ant-ling"
+    ]).optional(),
+    zaiToolStream: z.boolean().optional()
+  }).strict()
+}).strict().superRefine((config, ctx) => {
+  if (config.maxTokens > config.contextWindow) {
+    ctx.addIssue({ code: "custom", path: ["maxTokens"], message: "Pi maximum output cannot exceed its context window" });
+  }
+  if (config.reasoning && config.thinkingLevelMap[config.thinkingLevel] === null) {
+    ctx.addIssue({ code: "custom", path: ["thinkingLevel"], message: "Pi thinking level is not supported by the declared model" });
+  }
+  if (!config.reasoning && config.thinkingLevel !== "off") {
+    ctx.addIssue({ code: "custom", path: ["thinkingLevel"], message: "Non-reasoning Pi models require thinking off" });
+  }
+});
 
 // src/provider-profile.ts
 var PROVIDER_PROFILE_REF_PATTERN = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/u;
@@ -251,6 +299,8 @@ var ModelProviderProfileSchema = z.object({
   enabled: z.boolean(),
   kind: z.literal("model"),
   model: boundedString("model", 160),
+  // Direct transports do not use Pi; Pi admission requires this explicit configuration.
+  pi_model: PiModelConfigSchema.optional(),
   profile_ref: ProviderProfileRefSchema,
   provider_kind: z.enum(MODEL_PROVIDER_KINDS),
   updated_at: isoTimestamp("updated_at")
@@ -309,6 +359,7 @@ function exactProviderProfileBinding(profileInput, requiredCapabilities = profil
     capabilities: normalizedCapabilities,
     kind: profile.kind,
     model: profile.model,
+    ...profile.pi_model === void 0 ? {} : { pi_model: profile.pi_model },
     profile_ref: profile.profile_ref,
     provider_kind: profile.provider_kind
   });
@@ -539,13 +590,13 @@ function assertKeychainPath(keychainPath) {
   }
   return keychainPath;
 }
-
-// src/pi-provider-projection.ts
 var PI_PROJECTED_KEY_ENV = "PI_PROVIDER_API_KEY";
+var PI_LAUNCHER_RUNTIME_ENTRIES = ["pi-rpc", "pi-prepared"];
 function piProjectionProviderId(profileRef) {
   return `byok-sdk-${profileRef}`;
 }
 function buildPiProviderProjection(profile) {
+  const { thinkingLevel: _, ...modelSettings } = requirePiModelConfig(profile);
   const projectedProviderId = piProjectionProviderId(profile.profile_ref);
   return {
     providers: {
@@ -556,6 +607,7 @@ function buildPiProviderProjection(profile) {
         ...profile.auth_mode === "bearer" ? { authHeader: true } : {},
         models: [
           {
+            ...modelSettings,
             id: profile.model,
             name: profile.display_name,
             input: [
@@ -569,10 +621,34 @@ function buildPiProviderProjection(profile) {
   };
 }
 function buildPiProviderArgs(profile, delegatedArgs) {
+  const config = requirePiModelConfig(profile);
+  if (delegatedArgs.length > 128) throw new Error("Pi launcher delegated argument limit exceeded");
   let modeCount = 0;
+  let extensionCount = 0;
+  const singleFlags = /* @__PURE__ */ new Set();
   for (let index = 0; index < delegatedArgs.length; index += 1) {
     const flag = delegatedArgs[index];
-    if (flag === "--no-tools") continue;
+    if (typeof flag !== "string" || /[\u0000\r\n]/u.test(flag)) throw new Error("Pi launcher argument must be single-line");
+    if (flag !== "--extension") {
+      if (singleFlags.has(flag)) throw new Error(`Pi launcher duplicate argument ${flag}`);
+      singleFlags.add(flag);
+    }
+    if (flag === "--no-tools" || flag === "--no-skills" || flag === "--no-extensions") continue;
+    if (flag === "--config") {
+      const value = delegatedArgs[++index];
+      if (typeof value !== "string" || !isAbsolute(value) || /[\u0000\r\n]/u.test(value)) {
+        throw new Error("Pi launcher --config requires an absolute single-line path");
+      }
+      continue;
+    }
+    if (flag === "--extension") {
+      const value = delegatedArgs[++index];
+      if (typeof value !== "string" || !isAbsolute(value) || /[\u0000\r\n]/u.test(value)) {
+        throw new Error("Pi launcher --extension requires an absolute single-line path");
+      }
+      if (++extensionCount > 16) throw new Error("Pi launcher extension limit exceeded");
+      continue;
+    }
     if (flag === "--mode") {
       modeCount += 1;
       const value = delegatedArgs[index + 1];
@@ -582,7 +658,7 @@ function buildPiProviderArgs(profile, delegatedArgs) {
     }
     if (flag === "--session" || flag === "--tools" || flag === "--exclude-tools") {
       const value = delegatedArgs[index + 1];
-      if (!value || value.startsWith("--")) {
+      if (!value || value.startsWith("--") || /[\u0000\r\n]/u.test(value)) {
         throw new Error(`${flag} requires a value`);
       }
       index += 1;
@@ -591,52 +667,47 @@ function buildPiProviderArgs(profile, delegatedArgs) {
     throw new Error(`Pi launcher does not allow delegated argument ${flag ?? "<missing>"}`);
   }
   if (modeCount !== 1) throw new Error("Pi launcher requires exactly one --mode rpc");
+  if (singleFlags.has("--no-tools") && singleFlags.has("--tools")) {
+    throw new Error("Pi launcher cannot combine --no-tools and --tools");
+  }
   return [
     ...delegatedArgs,
     "--provider",
     piProjectionProviderId(profile.profile_ref),
     "--model",
-    profile.model
+    profile.model,
+    "--thinking",
+    config.thinkingLevel
   ];
 }
+function buildPiPreparedArgs(delegatedArgs) {
+  if (delegatedArgs.length !== 2 || delegatedArgs[0] !== "--config") {
+    throw new Error("Pi prepared launcher requires exactly --config <path>");
+  }
+  const value = delegatedArgs[1];
+  if (typeof value !== "string" || !isAbsolute(value) || /[\u0000\r\n]/u.test(value)) {
+    throw new Error("Pi launcher --config requires an absolute single-line path");
+  }
+  return [...delegatedArgs];
+}
+function requirePiModelConfig(profile) {
+  if (profile.pi_model === void 0) throw new Error("Pi execution requires explicit pi_model configuration");
+  return PiModelConfigSchema.parse(profile.pi_model);
+}
 
 // src/pi-provider-launcher-core.ts
-var PI_CHILD_BASE_ENV_NAMES = [
-  "PATH",
-  "HOME",
-  "USERPROFILE",
-  "TMPDIR",
-  "TEMP",
-  "TMP",
-  "LANG",
-  "TZ",
-  "TERM",
-  "SHELL",
-  "HTTP_PROXY",
-  "HTTPS_PROXY",
-  "NO_PROXY",
-  "ALL_PROXY",
-  "http_proxy",
-  "https_proxy",
-  "no_proxy",
-  "all_proxy"
-];
-var PI_CHILD_WINDOWS_ENV_NAMES = [
-  "SystemRoot",
-  "COMSPEC",
-  "PATHEXT",
-  "windir",
-  "SYSTEMDRIVE",
-  "PROGRAMFILES",
-  "APPDATA",
-  "LOCALAPPDATA"
-];
 function parsePiProviderLauncherOptions(args) {
   const separator = args.indexOf("--");
   const ownArgs = separator < 0 ? args : args.slice(0, separator);
   const piArgs = separator < 0 ? [] : args.slice(separator + 1);
   const allowedFlags = /* @__PURE__ */ new Set([
     "--pi-bin",
+    "--pi-entry",
+    "--launch-binding",
+    "--pi-cwd",
+    "--pi-fixed-args",
+    "--pi-config-digest",
+    "--runtime-entry",
     "--profile-db",
     "--provider",
     "--model",
@@ -667,6 +738,11 @@ function parsePiProviderLauncherOptions(args) {
     if (value === void 0) throw new Error(`${flag} requires a value`);
     return value;
   };
+  const rawRuntimeEntry = required("--runtime-entry");
+  if (!PI_LAUNCHER_RUNTIME_ENTRIES.includes(rawRuntimeEntry)) {
+    throw new Error(`--runtime-entry must be one of [${PI_LAUNCHER_RUNTIME_ENTRIES.join(", ")}]`);
+  }
+  const runtimeEntry = rawRuntimeEntry;
   const rawProfileRef = required("--provider");
   const profileRef = ProviderProfileRefSchema.safeParse(rawProfileRef);
   if (!profileRef.success) {
@@ -725,8 +801,53 @@ function parsePiProviderLauncherOptions(args) {
       requiredCapabilities: parsedCapabilities.data
     };
   }
+  const piEntry = values.get("--pi-entry");
+  if (piEntry !== void 0 && (!path2.isAbsolute(piEntry) || /[\u0000\r\n]/u.test(piEntry))) {
+    throw new Error("--pi-entry requires an absolute single-line path");
+  }
+  let launchBinding;
+  let piCwd;
+  let piFixedArgs;
+  if (!validateOnly || ["--launch-binding", "--pi-cwd", "--pi-fixed-args"].some((flag) => values.has(flag))) {
+    let rawBinding;
+    let rawFixedArgs;
+    try {
+      rawBinding = JSON.parse(required("--launch-binding"));
+    } catch {
+      throw new Error("--launch-binding requires a valid JSON binding");
+    }
+    launchBinding = parseImplementationSpawnBinding(rawBinding);
+    if (launchBinding === void 0) throw new Error("invalid implementation spawn binding");
+    piCwd = required("--pi-cwd");
+    try {
+      rawFixedArgs = JSON.parse(required("--pi-fixed-args"));
+    } catch {
+      throw new Error("--pi-fixed-args requires a JSON array");
+    }
+    if (!Array.isArray(rawFixedArgs) || rawFixedArgs.some((arg) => typeof arg !== "string")) {
+      throw new Error("--pi-fixed-args requires a JSON array of strings");
+    }
+    piFixedArgs = rawFixedArgs;
+    if (launchBinding.command !== required("--pi-bin") || launchBinding.entry !== piEntry || launchBinding.cwd !== piCwd || JSON.stringify(launchBinding.fixedArgv) !== JSON.stringify(piFixedArgs)) {
+      throw new Error("launcher arguments differ from implementation spawn binding");
+    }
+    if (launchBinding.envCommitments.PI_CODING_AGENT_SESSION_DIR !== sessionDir || launchBinding.envCommitments.PI_CODING_AGENT_DIR === void 0) {
+      throw new Error("launcher session/projection directories must match binding commitments");
+    }
+  }
+  const piConfigDigest = values.get("--pi-config-digest");
+  if ((!validateOnly || piConfigDigest !== void 0) && !/^[0-9a-f]{64}$/u.test(piConfigDigest ?? "")) {
+    throw new Error("--pi-config-digest requires 64 lowercase hexadecimal characters");
+  }
+  if (piArgs.some((arg) => arg === "--config-digest" || arg.startsWith("--config-digest="))) {
+    throw new Error("delegated --config-digest override is forbidden");
+  }
   return {
+    ...piConfigDigest === void 0 ? {} : { piConfigDigest },
+    ...piEntry === void 0 ? {} : { piEntry },
+    runtimeEntry,
     piBin: required("--pi-bin"),
+    ...launchBinding === void 0 ? {} : { launchBinding, piCwd, piFixedArgs },
     profileDbPath,
     profileRef: profileRef.data,
     modelId,
@@ -738,6 +859,20 @@ function parsePiProviderLauncherOptions(args) {
     piArgs
   };
 }
+function assertPiPreparedProviderProfile(profile) {
+  if (profile.adapter === "anthropic") {
+    throw new ByokKeysError(
+      "PROVIDER_PROFILE_INVALID",
+      `${profile.profile_ref} speaks the anthropic adapter; the prepared runtime entry compiles openai-completions only`
+    );
+  }
+  if (profile.auth_mode === "none") {
+    throw new ByokKeysError(
+      "PROVIDER_PROFILE_INVALID",
+      `${profile.profile_ref} declares auth_mode "none"; the prepared runtime entry requires a provider credential`
+    );
+  }
+}
 async function resolvePiProviderSecret(profile, createStore) {
   if (profile.auth_mode === "none") return void 0;
   const secrets = createStore();
@@ -757,26 +892,139 @@ async function resolvePiProviderSecret(profile, createStore) {
   return secret;
 }
 function buildPiProviderChildEnvironment(options) {
-  const platform = options.platform ?? process.platform;
-  const exactNames = new Set([
-    ...PI_CHILD_BASE_ENV_NAMES,
-    ...platform === "win32" ? PI_CHILD_WINDOWS_ENV_NAMES : []
-  ].map((name) => platform === "win32" ? name.toUpperCase() : name));
-  const result = {};
-  for (const [name, value] of Object.entries(options.ambient)) {
-    if (value === void 0) continue;
-    const platformName = platform === "win32" ? name.toUpperCase() : name;
-    const isExact = exactNames.has(platformName);
-    const isPrefixed = platform === "win32" ? platformName.startsWith("LC_") || platformName.startsWith("XDG_") : name.startsWith("LC_") || name.startsWith("XDG_");
-    if (isExact || isPrefixed) result[name] = value;
-  }
-  result.PI_CODING_AGENT_DIR = options.projectionDir;
-  result.PI_CODING_AGENT_SESSION_DIR = options.sessionDir;
-  if (options.secret !== void 0) {
-    result[PI_PROJECTED_KEY_ENV] = options.secret;
-  }
+  const binding = parseImplementationSpawnBinding(options.binding);
+  if (binding === void 0) throw new Error("invalid implementation spawn binding");
+  if (binding.envCommitments.PI_CODING_AGENT_SESSION_DIR !== options.sessionDir || binding.envCommitments.PI_CODING_AGENT_DIR === void 0) {
+    throw new Error("launcher session/projection directories must match binding commitments");
+  }
+  const result = {
+    ...projectKeysPiInheritedEnvironment(options.ambient, options.platform),
+    ...binding.envCommitments
+  };
   return result;
 }
+var WINDOWS_PROJECTION_ACL_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+try {
+  $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  $acl = Get-Acl -LiteralPath ([string]$request.path)
+  $sidType = [System.Security.Principal.SecurityIdentifier]
+  $rules = @($acl.Access | ForEach-Object {
+    $sid = if ($_.IdentityReference -is [System.Security.Principal.SecurityIdentifier]) { $_.IdentityReference.Value } else { try { $_.IdentityReference.Translate($sidType).Value } catch { $null } }
+    [ordered]@{
+      sid = $sid
+      allow = $_.AccessControlType -eq [System.Security.AccessControl.AccessControlType]::Allow
+      fullControl = ($_.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -eq [System.Security.AccessControl.FileSystemRights]::FullControl
+      inherits = ($_.InheritanceFlags -band 3) -eq 3 -and $_.PropagationFlags -eq [System.Security.AccessControl.PropagationFlags]::None
+    }
+  })
+  [ordered]@{
+    reparsePoint = ((Get-Item -LiteralPath ([string]$request.path) -Force).Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0
+    owner = $acl.GetOwner($sidType).Value
+    currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+    protected = $acl.AreAccessRulesProtected
+    rules = $rules
+  } | ConvertTo-Json -Depth 4 -Compress
+} catch {
+  [Console]::Error.WriteLine('Pi projection ACL query failed')
+  exit 1
+}
+`;
+async function assertWindowsPiProjectionAcl(directory, options = {}) {
+  const systemRoot = options.systemRoot ?? process.env.SystemRoot;
+  if (systemRoot === void 0 || !path2.win32.isAbsolute(systemRoot) || /[\u0000\r\n]/u.test(systemRoot)) {
+    throw new Error("Windows SystemRoot must be an absolute path");
+  }
+  const result = await (options.run ?? runCommand)(
+    path2.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+    ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(WINDOWS_PROJECTION_ACL_SCRIPT, "utf16le").toString("base64")],
+    JSON.stringify({ path: directory })
+  );
+  if (result.exitCode !== 0) throw new Error("Pi projection ACL query failed");
+  let acl;
+  try {
+    acl = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("pi_projection_acl_invalid_json");
+  }
+  const recordObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+  if (!recordObject(acl) || Object.keys(acl).sort().join(",") !== "currentUser,owner,protected,reparsePoint,rules" || typeof acl.owner !== "string" || !/^S-1-[0-9-]+$/u.test(acl.owner) || typeof acl.currentUser !== "string" || !/^S-1-[0-9-]+$/u.test(acl.currentUser) || typeof acl.protected !== "boolean" || typeof acl.reparsePoint !== "boolean" || !Array.isArray(acl.rules)) {
+    throw new Error("pi_projection_acl_invalid_shape");
+  }
+  if (acl.reparsePoint) throw new Error("pi_projection_reparse_point: Pi projection path must be a non-symlink directory");
+  if (acl.owner !== acl.currentUser) throw new Error("pi_projection_owner_mismatch: Pi projection directory must be owned by the current user");
+  if (!acl.protected) throw new Error("pi_projection_acl_unprotected");
+  const principals = /* @__PURE__ */ new Set([acl.owner, "S-1-5-18", "S-1-5-32-544"]);
+  let ownerControl = false;
+  for (const rule of acl.rules) {
+    if (!recordObject(rule) || Object.keys(rule).sort().join(",") !== "allow,fullControl,inherits,sid" || typeof rule.sid !== "string" || !/^S-1-[0-9-]+$/u.test(rule.sid) || typeof rule.allow !== "boolean" || typeof rule.fullControl !== "boolean" || typeof rule.inherits !== "boolean") {
+      throw new Error("pi_projection_acl_invalid_ace");
+    }
+    if (!principals.has(rule.sid) || !rule.allow) throw new Error("pi_projection_acl_unauthorized_ace");
+    if (rule.sid === acl.owner && rule.fullControl && rule.inherits) ownerControl = true;
+  }
+  if (!ownerControl) throw new Error("pi_projection_acl_owner_access_missing");
+}
+async function assertPiProjectionDirectory(projectionDir, expectedDir) {
+  if (projectionDir !== expectedDir || !path2.isAbsolute(projectionDir) || path2.normalize(projectionDir) !== projectionDir) {
+    throw new Error("pi_projection_path_mismatch: Pi projection directory differs from committed path");
+  }
+  const stat = await promises.lstat(projectionDir);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("pi_projection_not_directory_or_symlink: Pi projection path must be a non-symlink directory");
+  if (await promises.realpath(projectionDir) !== projectionDir) throw new Error("pi_projection_path_not_canonical: Pi projection directory parents must be canonical, without symlinks");
+  if (process.platform === "win32") {
+    await assertWindowsPiProjectionAcl(projectionDir);
+  } else {
+    if (stat.uid !== process.getuid()) throw new Error("pi_projection_owner_mismatch: Pi projection directory must be owned by the current uid");
+    if ((stat.mode & 4095) !== 448) throw new Error("pi_projection_mode_mismatch: Pi projection directory must have mode 0700");
+  }
+  if ((await promises.readdir(projectionDir)).length !== 0) throw new Error("pi_projection_not_empty: Pi projection directory must be empty");
+}
+async function startPiProvider(profile, options, dependencies) {
+  const binding = options.launchBinding;
+  if (options.validateOnly || binding === void 0 || options.piCwd === void 0 || options.piFixedArgs === void 0 || !/^[0-9a-f]{64}$/u.test(options.piConfigDigest ?? "")) {
+    throw new Error("Pi launch requires an explicit spawn binding, cwd and fixed args");
+  }
+  const projection = buildPiProviderProjection(profile);
+  const delegated = options.runtimeEntry === "pi-prepared" ? buildPiPreparedArgs(options.piArgs) : buildPiProviderArgs(profile, options.piArgs);
+  const env = buildPiProviderChildEnvironment({
+    ambient: dependencies.ambient,
+    binding,
+    sessionDir: options.sessionDir});
+  const actual = { command: options.piBin, entry: options.piEntry, fixedArgv: [...options.piFixedArgs], cwd: options.piCwd, env };
+  await assertImplementationSpawnBinding(binding, actual);
+  const projectionDir = env.PI_CODING_AGENT_DIR;
+  await assertPiProjectionDirectory(projectionDir, binding.envCommitments.PI_CODING_AGENT_DIR);
+  await ensurePiSessionDirectory(options.sessionDir);
+  const modelsPath = path2.join(projectionDir, "models.json");
+  let created = false;
+  const cleanup = async () => {
+    if (created) {
+      await promises.unlink(modelsPath);
+      created = false;
+    }
+  };
+  try {
+    const file = await promises.open(modelsPath, "wx", 384);
+    created = true;
+    try {
+      await file.writeFile(`${JSON.stringify(projection)}
+`);
+    } finally {
+      await file.close();
+    }
+    const secret = await resolvePiProviderSecret(profile, dependencies.createSecretStore);
+    if (secret !== void 0) env[PI_PROJECTED_KEY_ENV] = secret;
+    const childArgs = [...actual.entry === void 0 ? [] : [actual.entry], ...actual.fixedArgv, `--config-digest=${options.piConfigDigest}`, ...delegated];
+    const spawnChild = dependencies.spawn ?? spawn;
+    await assertImplementationSpawnBinding(binding, actual);
+    const child = spawnChild(actual.command, childArgs, { env, cwd: actual.cwd, stdio: "inherit" });
+    return { child, cleanup };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+}
 async function ensurePiSessionDirectory(sessionDir) {
   const firstCreated = await promises.mkdir(sessionDir, { recursive: true, mode: 448 });
   if (firstCreated !== void 0) {
@@ -823,19 +1071,19 @@ function loadSqliteModule() {
     );
   }
 }
-function openSqliteDatabase(path4, options, faults) {
+function openSqliteDatabase(path3, options, faults) {
   const { DatabaseSync } = loadSqliteModule();
   const readOnly = options?.readOnly === true;
-  if (path4 !== ":memory:" && !readOnly) {
-    mkdirSync(dirname(path4), { mode: SECURE_DIR_MODE, recursive: true });
+  if (path3 !== ":memory:" && !readOnly) {
+    mkdirSync(dirname(path3), { mode: SECURE_DIR_MODE, recursive: true });
   }
-  const database = new DatabaseSync(path4, {
+  const database = new DatabaseSync(path3, {
     timeout: DEFAULT_BUSY_TIMEOUT_MS,
     ...options
   });
   try {
     faults?.onStep?.("after-open");
-    if (path4 !== ":memory:" && !readOnly) {
+    if (path3 !== ":memory:" && !readOnly) {
       database.exec("PRAGMA journal_mode = WAL");
       faults?.onStep?.("after-wal");
       database.exec("PRAGMA synchronous = FULL");
@@ -878,6 +1126,7 @@ CREATE TABLE IF NOT EXISTS provider_profile (
   base_url      TEXT NOT NULL,
   auth_mode     TEXT NOT NULL CHECK (auth_mode IN (${sqlList(PROVIDER_AUTH_MODES)})),
   model         TEXT NOT NULL,
+  pi_model      TEXT,
   capabilities  TEXT NOT NULL,
   enabled       INTEGER NOT NULL CHECK (enabled IN (0, 1)),
   created_at    TEXT NOT NULL,
@@ -887,7 +1136,7 @@ CREATE TABLE IF NOT EXISTS provider_profile (
 function normalizeTableDdl(sql) {
   return sql.replace(/\bIF\s+NOT\s+EXISTS\b/giu, "").replace(/\s+/gu, " ").trim().replace(/;$/u, "").trim();
 }
-function assertProviderProfileSchemaIsCurrent(database, path4) {
+function assertProviderProfileSchemaIsCurrent(database, path3) {
   const row = database.prepare(
     "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'provider_profile'"
   ).get();
@@ -896,7 +1145,7 @@ function assertProviderProfileSchemaIsCurrent(database, path4) {
   if (normalizeTableDdl(stored) === normalizeTableDdl(SCHEMA)) return;
   throw new ByokKeysError(
     "PROVIDER_STORE_SCHEMA_STALE",
-    `Provider profile store at ${path4} was created by a different @byok-sdk/keys schema; recreate the store file to continue`
+    `Provider profile store at ${path3} was created by a different @byok-sdk/keys schema; preserve this store and explicitly provision a separate current-schema store before continuing`
   );
 }
 var ENABLED_INDEX = `
@@ -978,8 +1227,8 @@ var SqliteProviderProfileStore = class {
       this.#database.prepare(
         `INSERT INTO provider_profile (
              profile_ref, provider_kind, kind, adapter, display_name, base_url,
-             auth_mode, model, capabilities, enabled, created_at, updated_at
-           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+             auth_mode, model, pi_model, capabilities, enabled, created_at, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(profile_ref) DO UPDATE SET
              provider_kind = excluded.provider_kind,
              adapter = excluded.adapter,
@@ -987,6 +1236,7 @@ var SqliteProviderProfileStore = class {
              base_url = excluded.base_url,
              auth_mode = excluded.auth_mode,
              model = excluded.model,
+             pi_model = excluded.pi_model,
              capabilities = excluded.capabilities,
              enabled = excluded.enabled,
              updated_at = excluded.updated_at`
@@ -999,6 +1249,7 @@ var SqliteProviderProfileStore = class {
         validated.base_url,
         validated.auth_mode,
         validated.model,
+        validated.pi_model === void 0 ? null : JSON.stringify(validated.pi_model),
         JSON.stringify(validated.capabilities),
         validated.enabled ? 1 : 0,
         validated.created_at,
@@ -1037,6 +1288,7 @@ function parseRow(row) {
   }
   return parseModelProviderProfile({
     ...row,
+    pi_model: row.pi_model === null ? void 0 : JSON.parse(row.pi_model),
     capabilities,
     enabled: row.enabled === 1
   });
@@ -1343,7 +1595,7 @@ async function run(options) {
     path: options.profileDbPath,
     readOnly: true
   });
-  let projectionDir;
+  let cleanup;
   try {
     const profile = await profiles.get(options.profileRef);
     if (profile === void 0) {
@@ -1357,33 +1609,15 @@ async function run(options) {
     if (options.expectedBinding !== void 0) {
       assertExactProviderProfileBinding(profile, options.expectedBinding);
     }
+    if (options.runtimeEntry === "pi-prepared") assertPiPreparedProviderProfile(profile);
+    buildPiProviderProjection(profile);
     if (options.validateOnly) return 0;
-    const secret = await resolvePiProviderSecret(
-      profile,
-      () => createSecretStore(
-        options.secretServicePrefix,
-        options.macosKeychainPath
-      )
-    );
-    projectionDir = await promises.mkdtemp(path2.join(os.tmpdir(), "byok-pi-provider-"));
-    await promises.chmod(projectionDir, 448).catch(() => {
-    });
-    await ensurePiSessionDirectory(options.sessionDir);
-    await promises.writeFile(
-      path2.join(projectionDir, "models.json"),
-      `${JSON.stringify(buildPiProviderProjection(profile))}
-`,
-      { mode: 384 }
-    );
-    const child = spawn(options.piBin, buildPiProviderArgs(profile, options.piArgs), {
-      env: buildPiProviderChildEnvironment({
-        ambient: process.env,
-        projectionDir,
-        sessionDir: options.sessionDir,
-        secret
-      }),
-      stdio: "inherit"
+    const launched = await startPiProvider(profile, options, {
+      ambient: process.env,
+      createSecretStore: () => createSecretStore(options.secretServicePrefix, options.macosKeychainPath)
     });
+    cleanup = launched.cleanup;
+    const child = launched.child;
     const forward = (signal) => {
       if (!child.killed) child.kill(signal);
     };
@@ -1404,9 +1638,7 @@ async function run(options) {
     }
   } finally {
     await profiles.close();
-    if (projectionDir) {
-      await promises.rm(projectionDir, { recursive: true, force: true });
-    }
+    await cleanup?.();
   }
 }
 async function main() {