@the-open-engine/zeroshot 6.36.0 → 6.38.0

package/src/agent-cli-provider/adapters/pi.ts

@@ -1,15 +1,9 @@
 import { appendJsonSchemaPrompt } from '../schema';
 import { contractError } from '../contract-errors';
-import {
-  emitAssistantSnapshot,
-  parseAssistantDelta,
-  parseToolExecutionEnd,
-  parseToolExecutionStart,
-  parseToolExecutionUpdate,
-  parseTurnEndResult,
-  resetAssistantSnapshot,
-} from '../assistant-stream';
-import { getRecord, getString, isRecord, tryParseJson, unknownToMessage } from '../json';
+import { unknownToMessage } from '../json';
+import { PI_CREDENTIAL_ENV_KEYS } from '../pi/credentials';
+import { createPiParserState, finishPiParsing, parsePiEvent } from '../pi/events';
+import { PI_SUPPORTED_VERSION } from '../pi/release';
 import {
   type BuildProviderCommandOptions,
   type CommandSpec,
@@ -18,17 +12,15 @@ import {
   type LevelOverrides,
   type ModelCatalogEntry,
   type ModelLevel,
-  type OutputEvent,
   type PiCliFeatures,
   type ProviderAdapter,
-  type ProviderParserState,
   type ResolvedModelSpec,
   type WarningMetadata,
 } from '../types';
 import {
   classifyBaseProviderError,
   commandSpec,
-  createParserState,
+  isCliVersionAtLeast,
   optionFeatures,
   resolveModelSpecWithConfig,
   warning,
@@ -37,45 +29,104 @@ import {
 const MODEL_CATALOG: Readonly<Record<string, ModelCatalogEntry>> = {};
 
 const LEVEL_MAPPING: Readonly<Record<ModelLevel, LevelModelSpec>> = {
-  level1: { rank: 1, model: null },
-  level2: { rank: 2, model: null },
-  level3: { rank: 3, model: null },
+  level1: { rank: 1, model: null, reasoningEffort: 'low' },
+  level2: { rank: 2, model: null, reasoningEffort: 'medium' },
+  level3: { rank: 3, model: null, reasoningEffort: 'high' },
 };
 
-const IGNORED_EVENT_TYPES = new Set([
-  'session',
-  'agent_start',
-  'agent_end',
-  'turn_start',
-  'queue_update',
-  'compaction_start',
-  'compaction_end',
-  'auto_retry_start',
-  'auto_retry_end',
-]);
+function supportsFlag(
+  help: string,
+  assumeCurrent: boolean,
+  versionMatches: boolean,
+  pattern: RegExp
+): boolean {
+  return versionMatches && (assumeCurrent || pattern.test(help));
+}
 
-function detectCliFeatures(helpText?: string | null): PiCliFeatures {
+function detectCliFeatures(helpText?: string | null, versionText?: string | null): PiCliFeatures {
   const help = helpText ?? '';
-  const unknown = !help;
+  const versionMatches = isCliVersionAtLeast(versionText, PI_SUPPORTED_VERSION);
+  const assumeCurrent = !help && versionMatches;
   return {
     provider: 'pi',
-    supportsJsonMode: unknown ? true : /--mode\b/.test(help) && /\bjson\b/.test(help),
-    supportsModel: unknown ? true : /--model\b/.test(help),
-    supportsNoSession: unknown ? true : /--no-session\b/.test(help),
-    supportsNoExtensions: unknown ? true : /--no-extensions\b/.test(help),
-    supportsNoSkills: unknown ? true : /--no-skills\b/.test(help),
-    supportsNoPromptTemplates: unknown ? true : /--no-prompt-templates\b/.test(help),
-    supportsNoContextFiles: unknown ? true : /--no-context-files\b/.test(help),
-    supportsNoApprove: unknown ? true : /--no-approve\b/.test(help),
-    unknown,
+    versionMatches,
+    supportsJsonMode:
+      supportsFlag(help, assumeCurrent, versionMatches, /--mode\b/) &&
+      (assumeCurrent || /\bjson\b/.test(help)),
+    supportsModel: supportsFlag(help, assumeCurrent, versionMatches, /--model\b/),
+    supportsThinking: supportsFlag(help, assumeCurrent, versionMatches, /--thinking\b/),
+    supportsNoSession: supportsFlag(help, assumeCurrent, versionMatches, /--no-session\b/),
+    supportsNoExtensions: supportsFlag(help, assumeCurrent, versionMatches, /--no-extensions\b/),
+    supportsNoSkills: supportsFlag(help, assumeCurrent, versionMatches, /--no-skills\b/),
+    supportsNoPromptTemplates: supportsFlag(
+      help,
+      assumeCurrent,
+      versionMatches,
+      /--no-prompt-templates\b/
+    ),
+    supportsNoContextFiles: supportsFlag(
+      help,
+      assumeCurrent,
+      versionMatches,
+      /--no-context-files\b/
+    ),
+    supportsNoApprove: supportsFlag(help, assumeCurrent, versionMatches, /--no-approve\b/),
+    unknown: !help || !(versionText ?? '').trim(),
   };
 }
 
+function assertRequiredControls(options: BuildProviderCommandOptions): void {
+  const features = optionFeatures(options);
+  if (features.versionMatches !== true) {
+    throw contractError({
+      code: 'invalid-field',
+      field: 'options.cliFeatures.versionMatches',
+      exitCode: 2,
+      message:
+        `Pi ${PI_SUPPORTED_VERSION} or newer is required for the agent_settled JSON protocol. ` +
+        `Upgrade with: npm install -g --ignore-scripts ` +
+        `@earendil-works/pi-coding-agent@${PI_SUPPORTED_VERSION}`,
+    });
+  }
+  const required = [
+    ['supportsJsonMode', '--mode json'],
+    ['supportsNoSession', '--no-session'],
+    ['supportsNoSkills', '--no-skills'],
+    ['supportsNoPromptTemplates', '--no-prompt-templates'],
+    ['supportsNoContextFiles', '--no-context-files'],
+    ['supportsNoApprove', '--no-approve'],
+  ] as const;
+  for (const [field, flag] of required) {
+    if (features[field] !== false) continue;
+    throw contractError({
+      code: 'invalid-field',
+      field: `options.cliFeatures.${field}`,
+      exitCode: 2,
+      message: `Pi ${PI_SUPPORTED_VERSION}+ support for ${flag} is required for Zeroshot execution.`,
+    });
+  }
+  if (options.modelSpec?.model && features.supportsModel === false) {
+    throw contractError({
+      code: 'invalid-field',
+      field: 'options.cliFeatures.supportsModel',
+      exitCode: 2,
+      message: `Pi ${PI_SUPPORTED_VERSION}+ support for --model is required for explicit model selection.`,
+    });
+  }
+  if (options.modelSpec?.reasoningEffort && features.supportsThinking === false) {
+    throw contractError({
+      code: 'invalid-field',
+      field: 'options.cliFeatures.supportsThinking',
+      exitCode: 2,
+      message: `Pi ${PI_SUPPORTED_VERSION}+ support for --thinking is required for reasoning effort.`,
+    });
+  }
+}
+
 function addRequiredArgs(args: string[], options: BuildProviderCommandOptions): void {
   const features = optionFeatures(options);
   if (features.supportsJsonMode !== false) args.push('--mode', 'json');
   if (features.supportsNoSession !== false) args.push('--no-session');
-  if (features.supportsNoExtensions !== false) args.push('--no-extensions');
   if (features.supportsNoSkills !== false) args.push('--no-skills');
   if (features.supportsNoPromptTemplates !== false) args.push('--no-prompt-templates');
   if (features.supportsNoContextFiles !== false) args.push('--no-context-files');
@@ -87,6 +138,9 @@ function addOptionalArgs(args: string[], options: BuildProviderCommandOptions):
   if (options.modelSpec?.model && features.supportsModel !== false) {
     args.push('--model', options.modelSpec.model);
   }
+  if (options.modelSpec?.reasoningEffort && features.supportsThinking !== false) {
+    args.push('--thinking', options.modelSpec.reasoningEffort);
+  }
 }
 
 function failClosedUnsupportedSessionControl(options: BuildProviderCommandOptions): void {
@@ -98,12 +152,11 @@ function failClosedUnsupportedSessionControl(options: BuildProviderCommandOption
     field,
     exitCode: 2,
     message:
-      'Pi CLI does not support resume/continue session control; fail closed and start a fresh run instead.',
+      'Pi CLI does not support resume/continue session control with a task-owned identity boundary.',
   });
 }
 
 function collectWarnings(options: BuildProviderCommandOptions): WarningMetadata[] {
-  const features = optionFeatures(options);
   const warnings: WarningMetadata[] = [];
 
   if (options.jsonSchema) {
@@ -115,16 +168,12 @@ function collectWarnings(options: BuildProviderCommandOptions): WarningMetadata[
       )
     );
   }
-  if (features.supportsJsonMode === false) {
-    warnings.push(
-      warning('pi', 'pi-json-mode', 'Pi CLI does not advertise --mode json; continuing anyway.')
-    );
-  }
   return warnings;
 }
 
 function buildCommand(context: string, options: BuildProviderCommandOptions = {}): CommandSpec {
   failClosedUnsupportedSessionControl(options);
+  assertRequiredControls(options);
   const finalContext = options.jsonSchema
     ? appendJsonSchemaPrompt(context, options.jsonSchema)
     : context;
@@ -132,7 +181,9 @@ function buildCommand(context: string, options: BuildProviderCommandOptions = {}
 
   addRequiredArgs(args, options);
   addOptionalArgs(args, options);
-  args.push(finalContext);
+  // Pi has no `--` end-of-options sentinel and interprets leading `-`/`@` positional values as
+  // flags or file arguments. A leading space keeps arbitrary Zeroshot context in prompt mode.
+  args.push(` ${finalContext}`);
 
   return commandSpec({
     binary: 'pi',
@@ -143,80 +194,6 @@ function buildCommand(context: string, options: BuildProviderCommandOptions = {}
   });
 }
 
-function createPiState(): ProviderParserState {
-  return {
-    ...createParserState('pi'),
-    lastAssistantText: '',
-    lastAssistantThinking: '',
-  };
-}
-
-function parsePiTurnEnd(
-  event: Record<string, unknown>,
-  state: ProviderParserState
-): readonly OutputEvent[] {
-  const message = getRecord(event, 'message');
-  const events = message === null ? [] : [...emitAssistantSnapshot(message, state)];
-  events.push(parseTurnEndResult(event, { failureMessage: 'Pi turn failed' }));
-  return events;
-}
-
-function parseMessageEvent(
-  type: string,
-  event: Record<string, unknown>,
-  state: ProviderParserState
-): readonly OutputEvent[] | OutputEvent | null | undefined {
-  if (type === 'message_start') {
-    resetAssistantSnapshot(getRecord(event, 'message'), state);
-    return null;
-  }
-
-  if (type === 'message_update') {
-    const assistantMessageEvent = getRecord(event, 'assistantMessageEvent');
-    if (assistantMessageEvent !== null) {
-      const assistantEvent = parseAssistantDelta(assistantMessageEvent, state);
-      if (assistantEvent !== null) return assistantEvent;
-    }
-    const message = getRecord(event, 'message');
-    return message === null ? null : emitAssistantSnapshot(message, state);
-  }
-
-  if (type !== 'message_end') return undefined;
-  const message = getRecord(event, 'message');
-  return message === null ? null : emitAssistantSnapshot(message, state);
-}
-
-function parseToolEvent(
-  type: string,
-  event: Record<string, unknown>,
-  state: ProviderParserState
-): OutputEvent | null | undefined {
-  if (type === 'tool_execution_start') return parseToolExecutionStart(event, state);
-  if (type === 'tool_execution_update') return parseToolExecutionUpdate(event, state);
-  if (type === 'tool_execution_end') return parseToolExecutionEnd(event, state);
-  return undefined;
-}
-
-function parseEvent(
-  line: string,
-  state: ProviderParserState
-): readonly OutputEvent[] | OutputEvent | null {
-  const parsed = tryParseJson(line);
-  if (!isRecord(parsed)) return null;
-
-  const type = getString(parsed, 'type');
-  if (type === null || IGNORED_EVENT_TYPES.has(type)) return null;
-
-  const messageEvent = parseMessageEvent(type, parsed, state);
-  if (messageEvent !== undefined) return messageEvent;
-
-  const toolEvent = parseToolEvent(type, parsed, state);
-  if (toolEvent !== undefined) return toolEvent;
-
-  if (type === 'turn_end') return parsePiTurnEnd(parsed, state);
-  return null;
-}
-
 function resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): ResolvedModelSpec {
   return resolveModelSpecWithConfig({
     mapping: LEVEL_MAPPING,
@@ -250,7 +227,9 @@ function classifyError(error: unknown): ErrorClassification {
       /\b(cancelled|canceled|aborted|interrupted)\b/i,
       /\brun\s*\/login\b/i,
       /\bmissing api key\b/i,
+      /\bno api key found\b/i,
       /\bno valid authentication\b/i,
+      /\bmodel\b.*\bnot found\b/i,
       /\bunknown option\b/i,
       /\bfailed to load\b/i,
       /\bcannot find module\b/i,
@@ -263,8 +242,8 @@ export const piAdapter: ProviderAdapter = {
   id: 'pi',
   displayName: 'Pi',
   binary: 'pi',
-  adapterVersion: '1',
-  credentialEnvKeys: [],
+  adapterVersion: '2',
+  credentialEnvKeys: PI_CREDENTIAL_ENV_KEYS,
   modelCatalog: MODEL_CATALOG,
   levelMapping: LEVEL_MAPPING,
   defaultLevel: 'level2',
@@ -272,8 +251,9 @@ export const piAdapter: ProviderAdapter = {
   defaultMinLevel: 'level1',
   detectCliFeatures,
   buildCommand,
-  parseEvent,
-  createParserState: createPiState,
+  parseEvent: parsePiEvent,
+  finishParsing: finishPiParsing,
+  createParserState: createPiParserState,
   resolveModelSpec,
   validateModelId,
   classifyError,

package/src/agent-cli-provider/contract-parse.ts

@@ -62,9 +62,16 @@ export function parseOutputEvents(
   }
 ): { readonly events: readonly OutputEvent[]; readonly diagnostics: readonly ContractEvidence[] } {
   const diagnostics = [...collectParseDiagnostics(fragments.sources)];
+  const protocolChunk =
+    adapter.id === 'pi'
+      ? ((
+          fragments.sources.find((source) => source.name === 'stdout') ??
+          fragments.sources.find((source) => source.name === 'jsonl')
+        )?.value ?? '')
+      : fragments.chunk;
   try {
     return {
-      events: parseProviderChunk(adapter.id, fragments.chunk),
+      events: parseProviderChunk(adapter.id, protocolChunk),
       diagnostics,
     };
   } catch (error) {

package/src/agent-cli-provider/invoke-evidence.ts

@@ -20,6 +20,16 @@ function classifyParsedFailure(
   });
 }
 
+function classifyMissingPiSettlement(
+  adapter: ProviderAdapter,
+  events: readonly OutputEvent[]
+): ErrorClassification | null {
+  if (adapter.id !== 'pi' || events.some((event) => event.type === 'result')) return null;
+  return classifyProviderError('pi', {
+    message: 'Pi JSON stream ended before agent_settled.',
+  });
+}
+
 export function providerFailureClassification(
   adapter: ProviderAdapter,
   result: ProcessResult,
@@ -31,7 +41,7 @@ export function providerFailureClassification(
     });
   }
   if (result.exitCode === 0 && result.signal === null) {
-    return classifyParsedFailure(adapter, events);
+    return classifyParsedFailure(adapter, events) ?? classifyMissingPiSettlement(adapter, events);
   }
   return classifyProviderError(adapter.id, {
     message: result.stderr || result.stdout || `Provider exited with code ${result.exitCode ?? ''}`,

package/src/agent-cli-provider/pi/credentials.ts

@@ -0,0 +1,47 @@
+export const PI_CREDENTIAL_ENV_KEYS = [
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_OAUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+  'ANT_LING_API_KEY',
+  'QWEN_TOKEN_PLAN_API_KEY',
+  'QWEN_TOKEN_PLAN_CN_API_KEY',
+  'OPENAI_API_KEY',
+  'AZURE_OPENAI_API_KEY',
+  'NVIDIA_API_KEY',
+  'DEEPSEEK_API_KEY',
+  'GEMINI_API_KEY',
+  'GOOGLE_CLOUD_API_KEY',
+  'GROQ_API_KEY',
+  'CEREBRAS_API_KEY',
+  'XAI_API_KEY',
+  'RADIUS_API_KEY',
+  'OPENROUTER_API_KEY',
+  'AI_GATEWAY_API_KEY',
+  'ZAI_API_KEY',
+  'ZAI_CODING_CN_API_KEY',
+  'MISTRAL_API_KEY',
+  'MINIMAX_API_KEY',
+  'MINIMAX_CN_API_KEY',
+  'MOONSHOT_API_KEY',
+  'HF_TOKEN',
+  'FIREWORKS_API_KEY',
+  'TOGETHER_API_KEY',
+  'BASETEN_API_KEY',
+  'OPENCODE_API_KEY',
+  'KIMI_API_KEY',
+  'CLOUDFLARE_API_KEY',
+  'XIAOMI_API_KEY',
+  'XIAOMI_TOKEN_PLAN_CN_API_KEY',
+  'XIAOMI_TOKEN_PLAN_AMS_API_KEY',
+  'XIAOMI_TOKEN_PLAN_SGP_API_KEY',
+  'COPILOT_GITHUB_TOKEN',
+  'AWS_ACCESS_KEY_ID',
+  'AWS_SECRET_ACCESS_KEY',
+  'AWS_SESSION_TOKEN',
+  'AWS_BEARER_TOKEN_BEDROCK',
+  'AWS_PROFILE',
+  'AWS_CONTAINER_CREDENTIALS_RELATIVE_URI',
+  'AWS_CONTAINER_CREDENTIALS_FULL_URI',
+  'AWS_WEB_IDENTITY_TOKEN_FILE',
+  'GOOGLE_APPLICATION_CREDENTIALS',
+] as const;

package/src/agent-cli-provider/pi/events.ts

@@ -0,0 +1,148 @@
+import {
+  emitAssistantSnapshot,
+  parseAssistantDelta,
+  parseToolExecutionEnd,
+  parseToolExecutionStart,
+  parseToolExecutionUpdate,
+  resetAssistantSnapshot,
+} from '../assistant-stream';
+import { getRecord, getString, isRecord, tryParseJson } from '../json';
+import type { OutputEvent, ProviderParserState } from '../types';
+import {
+  invalidatePiStream,
+  rememberPiAssistant,
+  rememberPiUsage,
+  settlePiStream,
+} from './protocol-state';
+
+const IGNORED_EVENT_TYPES = new Set([
+  'session',
+  'agent_start',
+  'agent_end',
+  'turn_start',
+  'queue_update',
+  'compaction_start',
+  'compaction_end',
+  'auto_retry_start',
+  'auto_retry_end',
+]);
+const settledStates = new WeakSet<ProviderParserState>();
+
+export function createPiParserState(): ProviderParserState {
+  return {
+    provider: 'pi',
+    lastToolId: undefined,
+    lastAssistantText: '',
+    lastAssistantThinking: '',
+  };
+}
+
+function parseMessageEvent(
+  type: string,
+  event: Record<string, unknown>,
+  state: ProviderParserState
+): readonly OutputEvent[] | OutputEvent | null | undefined {
+  if (type === 'message_start') {
+    resetAssistantSnapshot(getRecord(event, 'message'), state);
+    return null;
+  }
+  if (type === 'message_update') {
+    const assistantMessageEvent = getRecord(event, 'assistantMessageEvent');
+    if (assistantMessageEvent !== null) {
+      const assistantEvent = parseAssistantDelta(assistantMessageEvent, state);
+      if (assistantEvent !== null) return assistantEvent;
+    }
+    const message = getRecord(event, 'message');
+    return message === null ? null : emitAssistantSnapshot(message, state);
+  }
+  if (type !== 'message_end') return undefined;
+
+  const message = getRecord(event, 'message');
+  if (
+    message !== null &&
+    getString(message, 'role') === 'toolResult' &&
+    Object.hasOwn(message, 'usage')
+  ) {
+    rememberPiUsage(getRecord(message, 'usage'), state, 'Pi tool usage');
+  }
+  rememberPiAssistant(message, state);
+  return message === null || getString(message, 'role') !== 'assistant'
+    ? null
+    : emitAssistantSnapshot(message, state);
+}
+
+function parseToolEvent(
+  type: string,
+  event: Record<string, unknown>,
+  state: ProviderParserState
+): OutputEvent | null | undefined {
+  if (type === 'tool_execution_start') return parseToolExecutionStart(event, state);
+  if (type === 'tool_execution_update') return parseToolExecutionUpdate(event, state);
+  if (type === 'tool_execution_end') return parseToolExecutionEnd(event, state);
+  return undefined;
+}
+
+function parseKnownPiEvent(
+  type: string,
+  parsed: Record<string, unknown>,
+  state: ProviderParserState
+): readonly OutputEvent[] | OutputEvent | null {
+  if (type === 'compaction_end') {
+    const result = getRecord(parsed, 'result');
+    if (result !== null && Object.hasOwn(result, 'usage')) {
+      rememberPiUsage(getRecord(result, 'usage'), state, 'Pi compaction usage');
+    }
+    return null;
+  }
+  if (type === 'entry_appended') {
+    const entry = getRecord(parsed, 'entry');
+    if (
+      entry !== null &&
+      getString(entry, 'type') === 'branch_summary' &&
+      Object.hasOwn(entry, 'usage')
+    ) {
+      rememberPiUsage(getRecord(entry, 'usage'), state, 'Pi branch summary usage');
+    }
+    return null;
+  }
+  if (IGNORED_EVENT_TYPES.has(type)) return null;
+  const messageEvent = parseMessageEvent(type, parsed, state);
+  if (messageEvent !== undefined) return messageEvent;
+  const toolEvent = parseToolEvent(type, parsed, state);
+  if (toolEvent !== undefined) return toolEvent;
+  if (type === 'turn_end') {
+    const message = getRecord(parsed, 'message');
+    return message === null ? [] : emitAssistantSnapshot(message, state);
+  }
+  if (type !== 'agent_settled') return null;
+  settledStates.add(state);
+  return settlePiStream(state);
+}
+
+export function parsePiEvent(
+  line: string,
+  state: ProviderParserState
+): readonly OutputEvent[] | OutputEvent | null {
+  if (line.trim() && settledStates.has(state)) {
+    invalidatePiStream(state, 'stdout contained output after agent_settled.');
+    return settlePiStream(state);
+  }
+  const parsed = tryParseJson(line);
+  if (!isRecord(parsed)) {
+    if (line.trim()) invalidatePiStream(state, 'stdout contained malformed JSON.');
+    return null;
+  }
+
+  const type = getString(parsed, 'type');
+  if (type === null) {
+    invalidatePiStream(state, 'an event was missing its type.');
+    return null;
+  }
+  return parseKnownPiEvent(type, parsed, state);
+}
+
+export function finishPiParsing(state: ProviderParserState): OutputEvent | null {
+  if (settledStates.has(state)) return null;
+  invalidatePiStream(state, 'stdout ended before agent_settled.');
+  return settlePiStream(state);
+}