@ai-sdk/harness-pi 1.0.71 → 1.0.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-pi",
-  "version": "1.0.71",
+  "version": "1.0.73",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,7 +30,7 @@
     "@earendil-works/pi-coding-agent": "^0.80.10",
     "pi-mcp-adapter": "2.12.1",
     "typebox": "^1.1.38",
-    "@ai-sdk/harness": "1.0.70",
+    "@ai-sdk/harness": "1.0.72",
     "@ai-sdk/provider-utils": "5.0.27"
   },
   "peerDependencies": {

package/src/index.ts

@@ -9,4 +9,4 @@ export const pi = createPi();
 export { createPi } from './pi-harness';
 export { VERSION } from './version';
 export type { PiHarnessSettings } from './pi-harness';
-export type { PiAuthOptions } from './pi-auth';
+export type { PiAuthenticationMode, PiAuthOptions } from './pi-auth';

package/src/pi-auth.ts

@@ -8,12 +8,20 @@ import { VERSION } from './version';
 type ProviderConfigInput = Parameters<ModelRegistry['registerProvider']>[1];
 
 /**
- * Pi auth options. Exactly one of `gateway` or `customEnv` is honoured
- * (precedence: explicit `customEnv`, then explicit `gateway`, then ambient
- * gateway from `process.env`). To use multiple providers, use `customEnv`
- * with the standard `<PREFIX>_API_KEY` / `<PREFIX>_BASE_URL` pattern.
+ * Pi auth options. Choose an explicit mode or rely on 'auto' (precedence:
+ * explicit gateway, then OpenAI / Anthropic / custom environment variables).
  */
-export type PiAuthOptions = {
+export type PiAuthenticationMode =
+  | 'auto'
+  | 'openai'
+  | 'anthropic'
+  | 'custom'
+  | 'ai-gateway';
+
+/**
+ * @deprecated Passing an object to auth options is deprecated. Use a `PiAuthenticationMode` string value ("auto" | "openai" | "anthropic" | "custom" | "ai-gateway") instead, and pass credentials via environment variables.
+ */
+export type LegacyPiAuthOptions = {
   readonly gateway?: {
     readonly apiKey?: string;
     readonly baseUrl?: string;
@@ -31,6 +39,8 @@ export type PiAuthOptions = {
   readonly customEnv?: Record<string, string>;
 };
 
+export type PiAuthOptions = PiAuthenticationMode | LegacyPiAuthOptions;
+
 const DEFAULT_GATEWAY_BASE_URL = 'https://ai-gateway.vercel.sh';
 const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1';
 const DEFAULT_ANTHROPIC_BASE_URL = 'https://api.anthropic.com';
@@ -90,22 +100,79 @@ export function resolvePiEnv({
   options: PiAuthOptions | undefined;
   env: NodeJS.ProcessEnv;
 }): Record<string, string> {
-  const customEnvConfigured = hasConfiguredValue(options?.customEnv);
+  const normalizedOptions = normalizePiAuthToLegacyAuth(options);
+  const customEnvConfigured = hasConfiguredValue(normalizedOptions?.customEnv);
   if (customEnvConfigured) {
-    return resolveCustomEnv({ customEnv: options!.customEnv ?? {} });
+    return resolveCustomEnv({ customEnv: normalizedOptions!.customEnv ?? {} });
   }
 
-  const gatewayConfigured = hasConfiguredValue(options?.gateway);
+  const gatewayConfigured = hasConfiguredValue(normalizedOptions?.gateway);
   const gatewayAuthFromEnv = getAiGatewayAuthFromEnv({ env });
   if (gatewayConfigured) {
-    const apiKey = options!.gateway?.apiKey ?? gatewayAuthFromEnv.apiKey;
-    const baseUrl = options!.gateway?.baseUrl ?? gatewayAuthFromEnv.baseUrl;
+    const apiKey =
+      normalizedOptions!.gateway?.apiKey ?? gatewayAuthFromEnv.apiKey;
+    const baseUrl =
+      normalizedOptions!.gateway?.baseUrl ?? gatewayAuthFromEnv.baseUrl;
     if (apiKey) {
       return { AI_GATEWAY_API_KEY: apiKey, AI_GATEWAY_BASE_URL: baseUrl };
     }
     return {};
   }
 
+  // Handle explicit string modes with process env
+  if (typeof options === 'string') {
+    switch (options) {
+      case 'openai':
+        if (env.OPENAI_API_KEY) {
+          return {
+            OPENAI_API_KEY: env.OPENAI_API_KEY,
+            ...(env.OPENAI_BASE_URL
+              ? { OPENAI_BASE_URL: env.OPENAI_BASE_URL }
+              : {}),
+          };
+        }
+        return {};
+      case 'anthropic':
+        if (env.ANTHROPIC_API_KEY) {
+          return {
+            ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY,
+            ...(env.ANTHROPIC_BASE_URL
+              ? { ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL }
+              : {}),
+            ...(env.ANTHROPIC_AUTH_TOKEN
+              ? { ANTHROPIC_AUTH_TOKEN: env.ANTHROPIC_AUTH_TOKEN }
+              : {}),
+          };
+        }
+        return {};
+      case 'custom': {
+        const result: Record<string, string> = {};
+        for (const [key, value] of Object.entries(env)) {
+          if (
+            value &&
+            (key.endsWith('_API_KEY') ||
+              key.endsWith('_BASE_URL') ||
+              key === 'ANTHROPIC_AUTH_TOKEN')
+          ) {
+            result[key] = value;
+          }
+        }
+        return result;
+      }
+      case 'ai-gateway':
+        if (gatewayAuthFromEnv.apiKey) {
+          return {
+            AI_GATEWAY_API_KEY: gatewayAuthFromEnv.apiKey,
+            AI_GATEWAY_BASE_URL: gatewayAuthFromEnv.baseUrl,
+          };
+        }
+        return {};
+      case 'auto':
+      default:
+        break;
+    }
+  }
+
   // Ambient gateway fallback.
   if (gatewayAuthFromEnv.apiKey) {
     return {
@@ -114,7 +181,19 @@ export function resolvePiEnv({
     };
   }
 
-  return {};
+  // 'auto' fallback: pick up any other provider credentials from the env.
+  const ambient: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (
+      value &&
+      (key.endsWith('_API_KEY') ||
+        key.endsWith('_BASE_URL') ||
+        key === 'ANTHROPIC_AUTH_TOKEN')
+    ) {
+      ambient[key] = value;
+    }
+  }
+  return ambient;
 }
 
 export async function registerPiProviders({
@@ -128,15 +207,105 @@ export async function registerPiProviders({
   registries: PiRegistries;
   clientApp?: string;
 }): Promise<void> {
-  if (hasConfiguredValue(options?.customEnv)) {
+  const normalizedOptions = normalizePiAuthToLegacyAuth(options);
+  if (hasConfiguredValue(normalizedOptions?.customEnv)) {
     await registerCustomProviders({
-      customEnv: options!.customEnv ?? {},
+      customEnv: normalizedOptions!.customEnv ?? {},
       registries,
       clientApp,
     });
     return;
   }
 
+  // Legacy customEnv was handled above. Everything else reduces to a mode:
+  // string modes pass through, `undefined` is 'auto', and legacy gateway
+  // objects fall through to the trailing gateway-registration block.
+  const mode =
+    typeof options === 'string' ? options : options == null ? 'auto' : 'legacy';
+
+  switch (mode) {
+    case 'openai': {
+      const env = pickOpenAIEnv(resolvedEnv);
+      await registerCustomProviders({
+        customEnv: { ...pickOpenAIEnv(process.env), ...env },
+        registries,
+        clientApp,
+      });
+      return;
+    }
+    case 'anthropic': {
+      const env = pickAnthropicEnv(resolvedEnv);
+      await registerCustomProviders({
+        customEnv: { ...pickAnthropicEnv(process.env), ...env },
+        registries,
+        clientApp,
+      });
+      return;
+    }
+    case 'custom': {
+      // 'custom' registers every provider with credentials in the env.
+      const env = pickProviderEnv(resolvedEnv);
+      await registerCustomProviders({
+        customEnv: { ...pickProviderEnv(process.env), ...env },
+        registries,
+        clientApp,
+      });
+      return;
+    }
+    case 'ai-gateway': {
+      const gatewayAuth = getAiGatewayAuthFromEnv({ env: process.env });
+      const gatewayApiKey =
+        resolvedEnv.AI_GATEWAY_API_KEY ?? gatewayAuth.apiKey;
+      const gatewayBaseUrl =
+        resolvedEnv.AI_GATEWAY_BASE_URL ?? gatewayAuth.baseUrl;
+      if (!gatewayApiKey) return;
+      await register({
+        registries,
+        provider: 'vercel-ai-gateway',
+        apiKey: gatewayApiKey,
+        config: createGatewayProviderConfig({
+          apiKey: gatewayApiKey,
+          baseUrl: gatewayBaseUrl,
+          clientApp,
+        }),
+      });
+      return;
+    }
+    case 'legacy':
+      break; // handled below
+    case 'auto':
+    default: {
+      // 'auto' (the default): prefer the AI Gateway; only when no gateway
+      // credentials exist, fall back to other providers found in the env.
+      const gatewayAuth = getAiGatewayAuthFromEnv({ env: process.env });
+      const gatewayApiKey =
+        resolvedEnv.AI_GATEWAY_API_KEY ?? gatewayAuth.apiKey;
+      const gatewayBaseUrl =
+        resolvedEnv.AI_GATEWAY_BASE_URL ?? gatewayAuth.baseUrl;
+      if (gatewayApiKey) {
+        await register({
+          registries,
+          provider: 'vercel-ai-gateway',
+          apiKey: gatewayApiKey,
+          config: createGatewayProviderConfig({
+            apiKey: gatewayApiKey,
+            baseUrl: gatewayBaseUrl,
+            clientApp,
+          }),
+        });
+        return;
+      }
+      const env = pickProviderEnv(resolvedEnv);
+      await registerCustomProviders({
+        customEnv: { ...pickProviderEnv(process.env), ...env },
+        registries,
+        clientApp,
+      });
+      return;
+    }
+  }
+
+  // Legacy explicit gateway object options.
   const apiKey = resolvedEnv.AI_GATEWAY_API_KEY;
   const baseUrl = resolvedEnv.AI_GATEWAY_BASE_URL;
   if (!apiKey || !baseUrl) return;
@@ -149,6 +318,76 @@ export async function registerPiProviders({
   });
 }
 
+function pickOpenAIEnv(
+  env: NodeJS.ProcessEnv | Record<string, string>,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (env.OPENAI_API_KEY) result.OPENAI_API_KEY = env.OPENAI_API_KEY;
+  if (env.OPENAI_BASE_URL) result.OPENAI_BASE_URL = env.OPENAI_BASE_URL;
+  return result;
+}
+
+function pickAnthropicEnv(
+  env: NodeJS.ProcessEnv | Record<string, string>,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (env.ANTHROPIC_API_KEY) result.ANTHROPIC_API_KEY = env.ANTHROPIC_API_KEY;
+  if (env.ANTHROPIC_BASE_URL)
+    result.ANTHROPIC_BASE_URL = env.ANTHROPIC_BASE_URL;
+  if (env.ANTHROPIC_AUTH_TOKEN)
+    result.ANTHROPIC_AUTH_TOKEN = env.ANTHROPIC_AUTH_TOKEN;
+  return result;
+}
+
+/**
+ * Filters an env object down to provider-credential keys (`*_API_KEY`,
+ * `*_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`). Pi does not read provider
+ * credentials from the environment itself — providers are only registered
+ * through `registerProvider` / `setRuntimeApiKey` — so we must extract the
+ * relevant entries before handing them to `registerCustomProviders`.
+ */
+function pickProviderEnv(
+  env: NodeJS.ProcessEnv | Record<string, string>,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (
+      value &&
+      (key.endsWith('_API_KEY') ||
+        key.endsWith('_BASE_URL') ||
+        key === 'ANTHROPIC_AUTH_TOKEN')
+    ) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function normalizePiAuthToLegacyAuth(
+  options: PiAuthOptions | undefined,
+): LegacyPiAuthOptions | undefined {
+  if (options == null || options === 'auto') {
+    return undefined;
+  }
+  if (typeof options === 'string') {
+    switch (options) {
+      case 'ai-gateway':
+        return { gateway: {} };
+      case 'custom':
+      case 'openai':
+      case 'anthropic':
+        return { customEnv: {} };
+      default:
+        return undefined;
+    }
+  }
+
+  console.warn(
+    '[pi] Passing an object to auth options is deprecated. Use a string mode ("auto" | "openai" | "anthropic" | "custom" | "ai-gateway") instead, and pass credentials via environment variables.',
+  );
+  return options;
+}
+
 function resolveCustomEnv({
   customEnv,
 }: {

package/src/pi-resume-state.ts

@@ -1,6 +1,6 @@
+import { createHash } from 'node:crypto';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import path from 'node:path';
-import { shellQuote } from '@ai-sdk/harness/utils';
 import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
@@ -24,8 +24,8 @@ const piSessionFileNameSchema = z
  * Schema for the adapter-specific portion of lifecycle state `data` produced
  * by Pi's resumable lifecycle methods. Carries the basename
  * (including extension) of the Pi session file. The actual session bytes live
- * in the sandbox under `${sessionWorkDir}/.pi-sessions/<sessionFileName>` so
- * they survive cross-process resume via the sandbox snapshot.
+ * in a private, session-scoped directory under sandbox HOME so they survive
+ * cross-process resume without appearing in the agent workspace.
  */
 export const piResumeStateSchema = z.looseObject({
   sessionFileName: piSessionFileNameSchema.optional(),
@@ -33,7 +33,32 @@ export const piResumeStateSchema = z.looseObject({
 
 export type PiResumeStateData = z.infer<typeof piResumeStateSchema>;
 
-const PI_SESSIONS_DIR = '.pi-sessions';
+export function resolvePiPrivateSessionDirectory(input: {
+  readonly sandboxHomeDir: string;
+  readonly sessionWorkDir: string;
+  readonly sessionId: string;
+}): string {
+  const sessionKey = createHash('sha256').update(input.sessionId).digest('hex');
+  const privateSessionDir = path.posix.join(
+    input.sandboxHomeDir,
+    '.ai-sdk',
+    'harness-pi',
+    sessionKey,
+  );
+  const relativePath = path.posix.relative(
+    input.sessionWorkDir,
+    privateSessionDir,
+  );
+  if (
+    relativePath === '' ||
+    (!relativePath.startsWith('../') && !path.posix.isAbsolute(relativePath))
+  ) {
+    throw new Error(
+      `Pi private session directory ${JSON.stringify(privateSessionDir)} must be outside sessionWorkDir ${JSON.stringify(input.sessionWorkDir)}.`,
+    );
+  }
+  return privateSessionDir;
+}
 
 function resolveContainedHostPath(input: {
   readonly baseDir: string;
@@ -56,10 +81,10 @@ function resolveContainedHostPath(input: {
 }
 
 function resolveContainedSandboxPath(input: {
-  readonly sessionWorkDir: string;
+  readonly privateSessionDir: string;
   readonly sessionFileName: string;
 }): string {
-  const sessionDir = path.posix.resolve(input.sessionWorkDir, PI_SESSIONS_DIR);
+  const sessionDir = path.posix.resolve(input.privateSessionDir);
   const filePath = path.posix.resolve(
     sessionDir,
     safePiSessionFileName(input.sessionFileName),
@@ -76,13 +101,13 @@ function resolveContainedSandboxPath(input: {
 }
 
 /**
- * Copy the Pi session file from the host's local mirror to a stable location
- * inside the sandbox workspace. Called during resumable lifecycle methods so
- * the session survives a sandbox snapshot or a process handoff.
+ * Copy the Pi session file from the host's local mirror to private sandbox
+ * state. Called during resumable lifecycle methods so the session survives a
+ * sandbox snapshot or a process handoff.
  */
 export async function persistSessionFileToSandbox(args: {
   readonly sandbox: Experimental_SandboxSession;
-  readonly sessionWorkDir: string;
+  readonly privateSessionDir: string;
   readonly hostSessionDir: string;
   readonly sessionFileName: string;
   readonly abortSignal?: AbortSignal;
@@ -93,14 +118,9 @@ export async function persistSessionFileToSandbox(args: {
   });
   const content = await readFile(hostPath);
   const remotePath = resolveContainedSandboxPath({
-    sessionWorkDir: args.sessionWorkDir,
+    privateSessionDir: args.privateSessionDir,
     sessionFileName: args.sessionFileName,
   });
-  // Ensure the parent dir exists in the sandbox before writing.
-  await args.sandbox.run({
-    command: `mkdir -p ${shellQuote(path.posix.dirname(remotePath))}`,
-    ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
-  });
   await args.sandbox.writeBinaryFile({
     path: remotePath,
     content,
@@ -116,20 +136,20 @@ export async function persistSessionFileToSandbox(args: {
  */
 export async function pullSessionFileFromSandbox(args: {
   readonly sandbox: Experimental_SandboxSession;
-  readonly sessionWorkDir: string;
+  readonly privateSessionDir: string;
   readonly hostSessionDir: string;
   readonly sessionFileName: string;
   readonly abortSignal?: AbortSignal;
 }): Promise<string | undefined> {
   const remotePath = resolveContainedSandboxPath({
-    sessionWorkDir: args.sessionWorkDir,
+    privateSessionDir: args.privateSessionDir,
     sessionFileName: args.sessionFileName,
   });
   const bytes = await args.sandbox.readBinaryFile({
     path: remotePath,
     ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
   });
-  if (!bytes) return undefined;
+  if (bytes == null) return undefined;
   await mkdir(args.hostSessionDir, { recursive: true });
   const hostPath = resolveContainedHostPath({
     baseDir: args.hostSessionDir,

package/src/pi-session.ts

@@ -44,6 +44,7 @@ import { writePiSkills } from './pi-skills';
 import {
   persistSessionFileToSandbox,
   pullSessionFileFromSandbox,
+  resolvePiPrivateSessionDirectory,
   safePiSessionFileName,
 } from './pi-resume-state';
 import {
@@ -289,16 +290,21 @@ export async function createPiSession(
   await mkdir(hostSessionDir, { recursive: true });
 
   const sandbox = input.sandboxSession.restricted();
+  const sandboxHomeDir = await resolveSandboxHomeDir({
+    sandbox,
+    ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
+  });
+  const privateSessionDir = resolvePiPrivateSessionDirectory({
+    sandboxHomeDir,
+    sessionWorkDir: input.sessionWorkDir,
+    sessionId: input.sessionId,
+  });
   const permissionMode = input.permissionMode ?? 'allow-all';
   let sandboxSkillRootDir: string | undefined;
   let harnessSkills: Skill[] = [];
 
   // Materialise harness-provided skills into sandbox HOME, not the workspace.
   if (input.skills.length > 0) {
-    const sandboxHomeDir = await resolveSandboxHomeDir({
-      sandbox,
-      ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
-    });
     sandboxSkillRootDir = path.posix.join(sandboxHomeDir, '.agents', 'skills');
     harnessSkills = createHarnessPiSkills({
       skills: input.skills,
@@ -321,7 +327,7 @@ export async function createPiSession(
     );
     resumeSessionFilePath = await pullSessionFileFromSandbox({
       sandbox,
-      sessionWorkDir: input.sessionWorkDir,
+      privateSessionDir,
       hostSessionDir,
       sessionFileName: resumeSessionFileName,
       ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
@@ -553,7 +559,7 @@ export async function createPiSession(
     if (!sessionFileName) return;
     await persistSessionFileToSandbox({
       sandbox,
-      sessionWorkDir: input.sessionWorkDir,
+      privateSessionDir,
       hostSessionDir,
       sessionFileName,
     });