@ai-sdk/harness-pi 0.0.0 → 1.0.0-beta.11

package/src/pi-auth.ts

@@ -0,0 +1,168 @@
+import type {
+  AuthStorage,
+  ModelRegistry,
+} from '@earendil-works/pi-coding-agent';
+
+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.
+ */
+export type PiAuthOptions = {
+  readonly gateway?: {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+  };
+  /**
+   * Resolved environment-variable pairs of the form `<PREFIX>_API_KEY` and
+   * (optionally) `<PREFIX>_BASE_URL`. Special-cased prefixes:
+   *  - `AI_GATEWAY` → registers `vercel-ai-gateway`
+   *  - `OPENAI`     → registers `openai`
+   *  - `ANTHROPIC`  → registers `anthropic` (`ANTHROPIC_AUTH_TOKEN` adds a
+   *                   bearer auth header)
+   * Any other `<PREFIX>_API_KEY` with a matching `<PREFIX>_BASE_URL` is
+   * registered as the lowercased, dash-separated prefix.
+   */
+  readonly customEnv?: Record<string, string>;
+};
+
+/**
+ * Env subset returned by `resolvePiAuth` for use by the Pi model resolver
+ * (it reads `AI_GATEWAY_API_KEY` / `VERCEL_OIDC_TOKEN` to decide whether
+ * to fall back to the default gateway model).
+ */
+export type PiResolverEnv = Record<string, string>;
+
+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';
+
+function register(
+  registries: { authStorage: AuthStorage; modelRegistry: ModelRegistry },
+  provider: string,
+  apiKey: string,
+  config: ProviderConfigInput,
+): void {
+  registries.authStorage.setRuntimeApiKey(provider, apiKey);
+  registries.modelRegistry.registerProvider(provider, config);
+}
+
+function hasConfiguredValue(value: unknown): boolean {
+  if (value == null) return false;
+  if (typeof value === 'string') return value.length > 0;
+  if (typeof value !== 'object') return true;
+  return Object.values(value).some(hasConfiguredValue);
+}
+
+export function resolvePiAuth(
+  options: PiAuthOptions | undefined,
+  env: NodeJS.ProcessEnv,
+  registries: { authStorage: AuthStorage; modelRegistry: ModelRegistry },
+): PiResolverEnv {
+  const customEnvConfigured = hasConfiguredValue(options?.customEnv);
+  const gatewayConfigured = hasConfiguredValue(options?.gateway);
+
+  if (customEnvConfigured) {
+    return applyCustomEnv(options!.customEnv ?? {}, registries);
+  }
+
+  if (gatewayConfigured) {
+    const apiKey = options!.gateway?.apiKey;
+    const baseUrl = options!.gateway?.baseUrl ?? DEFAULT_GATEWAY_BASE_URL;
+    if (apiKey) {
+      register(registries, 'vercel-ai-gateway', apiKey, {
+        apiKey,
+        baseUrl,
+        authHeader: true,
+      });
+      return { AI_GATEWAY_API_KEY: apiKey, AI_GATEWAY_BASE_URL: baseUrl };
+    }
+    return {};
+  }
+
+  // Ambient gateway fallback.
+  const ambientKey = env.AI_GATEWAY_API_KEY || env.VERCEL_OIDC_TOKEN;
+  if (ambientKey) {
+    const baseUrl = env.AI_GATEWAY_BASE_URL ?? DEFAULT_GATEWAY_BASE_URL;
+    register(registries, 'vercel-ai-gateway', ambientKey, {
+      apiKey: ambientKey,
+      baseUrl,
+      authHeader: true,
+    });
+    return { AI_GATEWAY_API_KEY: ambientKey, AI_GATEWAY_BASE_URL: baseUrl };
+  }
+
+  return {};
+}
+
+function applyCustomEnv(
+  customEnv: Record<string, string>,
+  registries: { authStorage: AuthStorage; modelRegistry: ModelRegistry },
+): PiResolverEnv {
+  const out: PiResolverEnv = {};
+
+  const gatewayKey = customEnv.AI_GATEWAY_API_KEY;
+  if (gatewayKey) {
+    const baseUrl = customEnv.AI_GATEWAY_BASE_URL ?? DEFAULT_GATEWAY_BASE_URL;
+    register(registries, 'vercel-ai-gateway', gatewayKey, {
+      apiKey: gatewayKey,
+      baseUrl,
+      authHeader: true,
+    });
+    out.AI_GATEWAY_API_KEY = gatewayKey;
+    out.AI_GATEWAY_BASE_URL = baseUrl;
+  }
+
+  if (customEnv.OPENAI_API_KEY) {
+    const baseUrl = customEnv.OPENAI_BASE_URL ?? DEFAULT_OPENAI_BASE_URL;
+    register(registries, 'openai', customEnv.OPENAI_API_KEY, {
+      apiKey: customEnv.OPENAI_API_KEY,
+      baseUrl,
+      authHeader: true,
+    });
+  }
+
+  if (customEnv.ANTHROPIC_API_KEY) {
+    const baseUrl = customEnv.ANTHROPIC_BASE_URL ?? DEFAULT_ANTHROPIC_BASE_URL;
+    register(registries, 'anthropic', customEnv.ANTHROPIC_API_KEY, {
+      apiKey: customEnv.ANTHROPIC_API_KEY,
+      baseUrl,
+      ...(customEnv.ANTHROPIC_AUTH_TOKEN
+        ? {
+            headers: {
+              authorization: `Bearer ${customEnv.ANTHROPIC_AUTH_TOKEN}`,
+            },
+          }
+        : {}),
+    });
+  }
+
+  for (const [name, apiKey] of Object.entries(customEnv)) {
+    if (!name.endsWith('_API_KEY') || !apiKey) {
+      continue;
+    }
+    const prefix = name.slice(0, -'_API_KEY'.length);
+    if (
+      prefix === 'AI_GATEWAY' ||
+      prefix === 'OPENAI' ||
+      prefix === 'ANTHROPIC'
+    ) {
+      continue;
+    }
+    const provider = prefix.toLowerCase().replace(/_/g, '-');
+    const baseUrl = customEnv[`${prefix}_BASE_URL`];
+    if (!baseUrl) {
+      continue;
+    }
+    register(registries, provider, apiKey, {
+      apiKey,
+      baseUrl,
+      authHeader: true,
+    });
+  }
+
+  return out;
+}

package/src/pi-events.ts

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+
+/**
+ * Pi `session.subscribe` emits a discriminated union of events. The exact
+ * shape evolves with Pi versions; we accept the events with `passthrough()`
+ * and extract only the fields we recognise. The `type` field is required
+ * and stringly-typed because Pi may add new types we want to ignore.
+ */
+export const piSessionEventSchema = z
+  .object({
+    type: z.string(),
+    assistantMessageEvent: z
+      .object({
+        type: z.string().optional(),
+        delta: z.string().optional(),
+      })
+      .passthrough()
+      .optional(),
+    toolCallId: z.string().optional(),
+    toolName: z.string().optional(),
+    args: z.unknown().optional(),
+    input: z.unknown().optional(),
+    result: z.unknown().optional(),
+    content: z.unknown().optional(),
+    isError: z.boolean().optional(),
+    // Compaction events (`compaction_start` / `compaction_end`). `result` (a
+    // `CompactionResult`) rides the shared `result` field above; `reason`
+    // distinguishes manual vs automatic (threshold/overflow) compaction.
+    reason: z.string().optional(),
+    aborted: z.boolean().optional(),
+    error: z
+      .union([
+        z.string(),
+        z
+          .object({
+            errorMessage: z.string().optional(),
+            stopReason: z.string().optional(),
+          })
+          .passthrough(),
+      ])
+      .optional(),
+    message: z
+      .object({
+        role: z.string().optional(),
+        content: z.unknown().optional(),
+        stopReason: z.string().optional(),
+        errorMessage: z.string().optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+export type PiSessionEvent = z.infer<typeof piSessionEventSchema>;
+
+/**
+ * Decode an unknown raw event into a `PiSessionEvent` if it looks like one.
+ * Returns `undefined` if it doesn't parse so the caller can skip it.
+ */
+export function parseNativeEvent(raw: unknown): PiSessionEvent | undefined {
+  const parsed = piSessionEventSchema.safeParse(raw);
+  return parsed.success ? parsed.data : undefined;
+}
+
+/**
+ * Detect whether a Pi event signals a terminal error for the current turn.
+ * Returns the error message if so. Mirrors the original adapter's
+ * `getPiTerminalError`.
+ */
+export function getPiTerminalError(event: PiSessionEvent): string | undefined {
+  const isTerminalStopReason = (value: string | undefined) =>
+    value === 'error' || value === 'aborted';
+
+  if (typeof event.error === 'string' && event.error.trim()) {
+    return event.error.trim();
+  }
+
+  if (event.error && typeof event.error === 'object') {
+    const errorMessage = event.error.errorMessage?.trim();
+    if (errorMessage) {
+      return errorMessage;
+    }
+    const stopReason = event.error.stopReason?.trim();
+    if (isTerminalStopReason(stopReason)) {
+      return stopReason;
+    }
+  }
+
+  const messageError = event.message?.errorMessage?.trim();
+  if (messageError) {
+    return messageError;
+  }
+
+  const messageStopReason = event.message?.stopReason?.trim();
+  if (isTerminalStopReason(messageStopReason)) {
+    return messageStopReason;
+  }
+
+  if (
+    event.isError &&
+    typeof event.content === 'string' &&
+    event.content.trim()
+  ) {
+    return event.content.trim();
+  }
+
+  return undefined;
+}
+
+/** Pull the assistant text from a `turn_end` / `message_end` event payload. */
+export function extractAssistantText(
+  message: PiSessionEvent['message'],
+): string {
+  if (!message || message.role !== 'assistant') {
+    return '';
+  }
+
+  if (typeof message.content === 'string') {
+    return message.content;
+  }
+
+  if (!Array.isArray(message.content)) {
+    return '';
+  }
+
+  return message.content
+    .flatMap(part => {
+      if (!part || typeof part !== 'object') {
+        return [];
+      }
+      const contentPart = part as Record<string, unknown>;
+      return contentPart.type === 'text' && typeof contentPart.text === 'string'
+        ? [contentPart.text]
+        : [];
+    })
+    .join('');
+}

package/src/pi-harness.ts

@@ -0,0 +1,145 @@
+import {
+  commonTool,
+  type HarnessV1,
+  type HarnessV1BuiltinTool,
+} from '@ai-sdk/harness';
+import { tool } from '@ai-sdk/provider-utils';
+import { z } from 'zod';
+import type { PiAuthOptions } from './pi-auth';
+import { piResumeStateSchema } from './pi-resume-state';
+import { createPiSession, type PiThinkingLevel } from './pi-session';
+
+/**
+ * Configuration knobs for `createPi`. Pi runs as an in-process Node library
+ * (no bridge), so there's no `port` or `startupTimeoutMs` to set.
+ */
+export type PiHarnessSettings = {
+  /** Where Pi sources API keys / gateway credentials from. */
+  readonly auth?: PiAuthOptions;
+  /**
+   * Pi model id (or name). Leaving this unset falls back to the AI Gateway
+   * default when `AI_GATEWAY_API_KEY` / `VERCEL_OIDC_TOKEN` is set, and to
+   * Pi's own resolution otherwise.
+   */
+  readonly model?: string;
+  /**
+   * Pi's extended-thinking budget level. Maps directly to the SDK's
+   * `thinkingLevel` option on `createAgentSession`.
+   */
+  readonly thinkingLevel?: PiThinkingLevel;
+};
+
+const PI_BUILTIN_TOOLS = {
+  read: commonTool('read', {
+    nativeName: 'read',
+    toolUseKind: 'readonly',
+    description: 'Read file contents.',
+    inputSchema: z.object({
+      file_path: z.string(),
+    }),
+  }),
+  write: commonTool('write', {
+    nativeName: 'write',
+    toolUseKind: 'edit',
+    description: 'Overwrite or create a file.',
+    inputSchema: z.object({
+      file_path: z.string(),
+      content: z.string(),
+    }),
+  }),
+  edit: commonTool('edit', {
+    nativeName: 'edit',
+    toolUseKind: 'edit',
+    description: 'Edit a file by exact string replacement.',
+    inputSchema: z.object({
+      file_path: z.string(),
+      old_string: z.string(),
+      new_string: z.string(),
+    }),
+  }),
+  bash: commonTool('bash', {
+    nativeName: 'bash',
+    toolUseKind: 'bash',
+    description: 'Execute a shell command in the sandbox.',
+    inputSchema: z.object({
+      command: z.string(),
+      timeout: z.number().optional(),
+    }),
+  }),
+  grep: commonTool('grep', {
+    nativeName: 'grep',
+    toolUseKind: 'readonly',
+    description: 'Search file contents with regex.',
+    inputSchema: z.object({
+      pattern: z.string(),
+      path: z.string().optional(),
+      glob: z.string().optional(),
+      ignoreCase: z.boolean().optional(),
+      literal: z.boolean().optional(),
+      context: z.number().optional(),
+      limit: z.number().optional(),
+    }),
+  }),
+  glob: commonTool('glob', {
+    nativeName: 'find',
+    toolUseKind: 'readonly',
+    description: 'Find files matching a glob pattern.',
+    inputSchema: z.object({
+      pattern: z.string(),
+      path: z.string().optional(),
+      limit: z.number().optional(),
+    }),
+  }),
+  ls: {
+    ...tool({
+      description: 'List directory entries.',
+      inputSchema: z.object({
+        path: z.string().optional(),
+        limit: z.number().optional(),
+      }),
+      outputSchema: z.unknown(),
+    }),
+    nativeName: 'ls',
+    toolUseKind: 'readonly',
+  } as HarnessV1BuiltinTool,
+} as const satisfies Record<string, HarnessV1BuiltinTool<any, any>>;
+
+export function createPi(
+  settings: PiHarnessSettings = {},
+): HarnessV1<typeof PI_BUILTIN_TOOLS> {
+  return {
+    specificationVersion: 'harness-v1',
+    harnessId: 'pi',
+    builtinTools: PI_BUILTIN_TOOLS,
+    supportsBuiltinToolApprovals: true,
+    lifecycleStateSchema: piResumeStateSchema,
+    doStart: async startOpts => {
+      const lifecycleState = startOpts.continueFrom ?? startOpts.resumeFrom;
+      const resumeData = lifecycleState?.data as
+        | { sessionFileName?: string }
+        | undefined;
+
+      return createPiSession({
+        sessionId: startOpts.sessionId,
+        sandboxSession: startOpts.sandboxSession,
+        sessionWorkDir: startOpts.sessionWorkDir,
+        skills: startOpts.skills ?? [],
+        settings: {
+          ...(settings.auth ? { auth: settings.auth } : {}),
+          ...(settings.model ? { model: settings.model } : {}),
+          ...(settings.thinkingLevel
+            ? { thinkingLevel: settings.thinkingLevel }
+            : {}),
+        },
+        isResume: lifecycleState != null,
+        permissionMode: startOpts.permissionMode,
+        ...(resumeData?.sessionFileName
+          ? { resumeSessionFileName: resumeData.sessionFileName }
+          : {}),
+        ...(startOpts.abortSignal
+          ? { abortSignal: startOpts.abortSignal }
+          : {}),
+      });
+    },
+  };
+}

package/src/pi-model-resolver.ts

@@ -0,0 +1,52 @@
+import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
+
+type PiModel = ReturnType<ModelRegistry['getAll']>[number];
+
+/**
+ * Default model id used when no `model` is configured AND gateway credentials
+ * are available in the environment. Looked up from Pi's own model registry —
+ * the entry must exist under the `vercel-ai-gateway` provider in
+ * `@earendil-works/pi-ai`'s catalog.
+ */
+export const DEFAULT_PI_GATEWAY_MODEL_ID = 'anthropic/claude-sonnet-4.6';
+
+export function createPiModelResolver(
+  modelRegistry: ModelRegistry,
+  env: NodeJS.ProcessEnv = process.env,
+) {
+  let cachedModels: PiModel[] | undefined;
+
+  const loadModels = (): PiModel[] => {
+    if (cachedModels) {
+      return cachedModels;
+    }
+    try {
+      cachedModels = modelRegistry.getAll();
+    } catch {
+      cachedModels = [];
+    }
+    return cachedModels;
+  };
+
+  return (modelId: string | undefined): PiModel | undefined => {
+    const useGateway = Boolean(env.AI_GATEWAY_API_KEY || env.VERCEL_OIDC_TOKEN);
+    const effectiveId =
+      modelId ?? (useGateway ? DEFAULT_PI_GATEWAY_MODEL_ID : undefined);
+    if (!effectiveId) return undefined;
+
+    const models = loadModels();
+    const matches = (m: PiModel) =>
+      m.id === effectiveId || m.name === effectiveId;
+
+    // When gateway creds are present, prefer the gateway-routed entry for the
+    // given id. Pi's catalog lists the same model id under multiple providers
+    // (e.g. `anthropic/claude-sonnet-4.6` exists under both `openrouter` and
+    // `vercel-ai-gateway`); without this preference Pi would dispatch through
+    // a provider we didn't register, which fails with "No API key found".
+    return (
+      (useGateway &&
+        models.find(m => m.provider === 'vercel-ai-gateway' && matches(m))) ||
+      models.find(matches)
+    );
+  };
+}

package/src/pi-paths.ts

@@ -0,0 +1,136 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+
+export interface PiPathMapper {
+  /** The host-side mirror directory Pi reads/writes through the workspace VFS. */
+  readonly hostWorkDir: string;
+  /** The sandbox-side working directory where tools actually operate. */
+  readonly sandboxWorkDir: string;
+  /**
+   * Translate a path the host sees (relative to `hostWorkDir`, or absolute
+   * inside it, or already a sandbox path) to the canonical sandbox path. Throws
+   * if the path would escape the workspace.
+   */
+  toSandboxPath(inputPath: string): string;
+  /**
+   * Translate a path for read-only tools. In addition to the workspace, this
+   * allows explicitly configured sandbox roots such as `$HOME/.agents/skills`.
+   */
+  toReadableSandboxPath(inputPath: string): string;
+  /** Translate any path to its POSIX-relative form under `sandboxWorkDir`. */
+  toRelativePath(inputPath: string): string;
+}
+
+export interface PiReadablePathRoot {
+  readonly sandboxDir: string;
+}
+
+export interface CreatePiPathMapperOptions {
+  readonly hostWorkDir: string;
+  readonly sandboxWorkDir: string;
+  readonly readableRoots?: ReadonlyArray<PiReadablePathRoot>;
+}
+
+function isInsidePath(parent: string, candidate: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return (
+    relative === '' ||
+    (!relative.startsWith('..') && !path.isAbsolute(relative))
+  );
+}
+
+function isInsidePosixPath(parent: string, candidate: string): boolean {
+  const relative = path.posix.relative(parent, candidate);
+  return (
+    relative === '' ||
+    (!relative.startsWith('..') && !path.posix.isAbsolute(relative))
+  );
+}
+
+function canonicalizeForContainment(inputPath: string): string {
+  try {
+    return realpathSync.native(inputPath);
+  } catch {
+    const parent = path.dirname(inputPath);
+    if (parent === inputPath) {
+      return inputPath;
+    }
+    return path.join(
+      canonicalizeForContainment(parent),
+      path.basename(inputPath),
+    );
+  }
+}
+
+export function createPiPathMapper(
+  options: CreatePiPathMapperOptions,
+): PiPathMapper {
+  const normalizedHost = path.resolve(options.hostWorkDir);
+  const normalizedSandbox = path.posix.normalize(options.sandboxWorkDir);
+  const canonicalHost = canonicalizeForContainment(normalizedHost);
+  const readableRoots =
+    options.readableRoots?.map(root => ({
+      sandboxDir: path.posix.normalize(root.sandboxDir),
+    })) ?? [];
+
+  const toWorkspaceSandboxPath = (inputPath: string): string => {
+    if (path.posix.isAbsolute(inputPath)) {
+      const normalizedInput = path.posix.normalize(inputPath);
+      if (isInsidePosixPath(normalizedSandbox, normalizedInput)) {
+        return normalizedInput;
+      }
+    }
+
+    const resolvedHost = path.isAbsolute(inputPath)
+      ? path.resolve(inputPath)
+      : path.resolve(normalizedHost, inputPath);
+    const canonicalResolvedHost = canonicalizeForContainment(resolvedHost);
+    if (
+      !isInsidePath(normalizedHost, resolvedHost) ||
+      !isInsidePath(canonicalHost, canonicalResolvedHost)
+    ) {
+      throw new Error(`Pi path escapes the workspace: ${inputPath}`);
+    }
+
+    const relative = path
+      .relative(normalizedHost, resolvedHost)
+      .split(path.sep)
+      .join('/');
+    return relative
+      ? path.posix.join(normalizedSandbox, relative)
+      : normalizedSandbox;
+  };
+
+  return {
+    hostWorkDir: normalizedHost,
+    sandboxWorkDir: normalizedSandbox,
+    toSandboxPath(inputPath: string) {
+      return toWorkspaceSandboxPath(inputPath);
+    },
+    toReadableSandboxPath(inputPath: string) {
+      if (path.posix.isAbsolute(inputPath)) {
+        const normalizedInput = path.posix.normalize(inputPath);
+        if (
+          isInsidePosixPath(normalizedSandbox, normalizedInput) ||
+          readableRoots.some(root =>
+            isInsidePosixPath(root.sandboxDir, normalizedInput),
+          )
+        ) {
+          return normalizedInput;
+        }
+      }
+
+      return toWorkspaceSandboxPath(inputPath);
+    },
+    toRelativePath(inputPath: string) {
+      const sandboxPath = path.posix.isAbsolute(inputPath)
+        ? path.posix.normalize(inputPath)
+        : path.posix.join(
+            normalizedSandbox,
+            inputPath.split(path.sep).join('/'),
+          );
+      const relative = path.posix.relative(normalizedSandbox, sandboxPath);
+      return relative || '.';
+    },
+  };
+}