@the-open-engine/zeroshot 6.38.1 → 6.39.1

package/src/agent/agent-config.ts

@@ -0,0 +1,285 @@
+/** Agent configuration validation and defaults. */
+
+import qualityGateSchema = require('./agent-quality-gate-schema');
+import settingsFacade = require('./agent-config-settings');
+
+type ModelLevel = 'level1' | 'level2' | 'level3';
+type JsonSchemaType = 'array' | 'boolean' | 'integer' | 'number' | 'object' | 'string';
+
+interface JsonSchema {
+  type?: JsonSchemaType;
+  description?: string;
+  enum?: string[];
+  items?: JsonSchema;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  anyOf?: JsonSchema[];
+}
+
+interface ModelRule extends Record<string, unknown> {
+  iterations?: unknown;
+  model?: string;
+  modelLevel?: string;
+}
+
+interface PromptRule extends Record<string, unknown> {}
+
+interface PromptOptions extends Record<string, unknown> {
+  initial?: string;
+  subsequent?: string;
+  iterations?: PromptRule[];
+  system?: string;
+}
+
+interface AgentTrigger extends Record<string, unknown> {
+  action?: string;
+}
+
+interface AgentConfig extends Record<string, unknown> {
+  id: string;
+  outputFormat?: string;
+  structuredOutput?: JsonSchema;
+  jsonSchema?: JsonSchema;
+  modelRules?: ModelRule[];
+  model?: string;
+  modelLevel?: string;
+  strictSchema?: boolean;
+  prompt?: string | PromptOptions | null;
+  timeout?: number | string | null;
+  maxIterations?: number;
+  staleDuration?: number;
+  enableLivenessCheck?: boolean;
+  triggers?: AgentTrigger[];
+  role?: string;
+  requiredQualityGates?: unknown;
+  hooks?: {
+    onComplete?: {
+      config?: {
+        content?: {
+          data?: {
+            qualityGates?: unknown;
+            [key: string]: unknown;
+          };
+        };
+      };
+    };
+  };
+}
+
+interface AgentConfigOptions extends Record<string, unknown> {
+  mockSpawnFn?: unknown;
+  taskRunner?: unknown;
+  testMode?: boolean;
+}
+
+type SettingsRecord = ReturnType<typeof settingsFacade.loadSettings>;
+
+interface StaticModelConfig {
+  type: 'static';
+  model: string | null;
+  modelLevel: string | null;
+}
+
+interface RulesModelConfig {
+  type: 'rules';
+  rules: ModelRule[];
+}
+
+type ModelConfig = StaticModelConfig | RulesModelConfig;
+type PromptConfig =
+  | { type: 'static'; system: string }
+  | { type: 'rules'; rules: PromptRule[] }
+  | null;
+
+type NormalizedAgentConfig = Omit<AgentConfig, 'timeout'> & {
+  modelConfig: ModelConfig;
+  promptConfig: PromptConfig;
+  maxIterations: number;
+  timeout: number;
+  staleDuration: number;
+  enableLivenessCheck: boolean;
+};
+
+const VALID_LEVELS: readonly ModelLevel[] = ['level1', 'level2', 'level3'];
+const DEFAULT_MAX_ITERATIONS = 100;
+const DEFAULT_TIMEOUT = 0;
+const DEFAULT_STALE_DURATION_MS = 30 * 60 * 1000;
+const DEFAULT_LIVENESS_CHECK_ENABLED = false;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isModelLevel(value: string): value is ModelLevel {
+  return value === 'level1' || value === 'level2' || value === 'level3';
+}
+
+const { loadSettings, validateModelAgainstMax, VALID_MODELS } = settingsFacade;
+const { applyValidatorQualityGateDefaults } = qualityGateSchema;
+
+function applyOutputDefaults(config: AgentConfig): void {
+  if (!config.outputFormat) config.outputFormat = 'json';
+  if (config.structuredOutput && !config.jsonSchema) config.jsonSchema = config.structuredOutput;
+  if (config.outputFormat === 'json' && !config.jsonSchema) {
+    config.jsonSchema = {
+      type: 'object',
+      properties: {
+        summary: { type: 'string', description: 'Brief summary of what was done' },
+        result: { type: 'string', description: 'Detailed result or output' },
+      },
+      required: ['summary', 'result'],
+    };
+  }
+  applyValidatorQualityGateDefaults(config);
+}
+
+function buildModelConfig(config: AgentConfig): ModelConfig {
+  if (config.modelRules) return { type: 'rules', rules: config.modelRules };
+  return { type: 'static', model: config.model || null, modelLevel: config.modelLevel || null };
+}
+
+function applyStrictSchemaDefault(config: AgentConfig, settings: SettingsRecord): void {
+  if (config.strictSchema === undefined) config.strictSchema = settings.strictSchema !== false;
+}
+
+function errorMessage(error: unknown): unknown {
+  return isRecord(error) ? error.message : undefined;
+}
+
+function validateStaticModelConfig(
+  configId: string,
+  modelConfig: StaticModelConfig,
+  maxModel: string,
+  minModel: string | null
+): void {
+  if (modelConfig.model && VALID_MODELS.includes(modelConfig.model)) {
+    try {
+      validateModelAgainstMax(modelConfig.model, maxModel, minModel);
+    } catch (error: unknown) {
+      throw new Error(`Agent "${configId}": ${String(errorMessage(error))}`);
+    }
+  }
+  if (modelConfig.modelLevel && !isModelLevel(modelConfig.modelLevel)) {
+    throw new Error(
+      `Agent "${configId}": invalid modelLevel "${modelConfig.modelLevel}". Valid: ${VALID_LEVELS.join(', ')}`
+    );
+  }
+}
+
+function validateModelRule(
+  configId: string,
+  rule: ModelRule,
+  maxModel: string,
+  minModel: string | null
+): void {
+  if (rule.model && VALID_MODELS.includes(rule.model)) {
+    try {
+      validateModelAgainstMax(rule.model, maxModel, minModel);
+    } catch {
+      throw new Error(
+        `Agent "${configId}": modelRule "${String(rule.iterations)}" requests "${rule.model}" ` +
+          `but maxModel is "${maxModel}"${minModel ? ` and minModel is "${minModel}"` : ''}. ` +
+          `Either adjust the rule's model or change maxModel/minModel settings.`
+      );
+    }
+  }
+  if (rule.modelLevel && !isModelLevel(rule.modelLevel)) {
+    throw new Error(
+      `Agent "${configId}": modelRule "${String(rule.iterations)}" has invalid modelLevel ` +
+        `"${rule.modelLevel}". Valid: ${VALID_LEVELS.join(', ')}`
+    );
+  }
+}
+
+function validateModelConfig(
+  config: AgentConfig,
+  modelConfig: ModelConfig,
+  maxModel: string,
+  minModel: string | null
+): void {
+  if (modelConfig.type === 'static') {
+    validateStaticModelConfig(config.id, modelConfig, maxModel, minModel);
+  } else {
+    for (const rule of modelConfig.rules) validateModelRule(config.id, rule, maxModel, minModel);
+  }
+}
+
+function buildInitialPromptRules(prompt: PromptOptions): PromptRule[] | null {
+  if (!prompt.initial && !prompt.subsequent) return null;
+  const rules: PromptRule[] = [];
+  if (prompt.initial) rules.push({ match: '1', system: prompt.initial });
+  if (prompt.subsequent) rules.push({ match: '2+', system: prompt.subsequent });
+  return rules;
+}
+
+function buildPromptConfig(config: AgentConfig): PromptConfig {
+  const prompt = config.prompt;
+  if (prompt && typeof prompt !== 'string' && prompt.iterations) {
+    return { type: 'rules', rules: prompt.iterations };
+  }
+  if (prompt && typeof prompt !== 'string') {
+    const initialRules = buildInitialPromptRules(prompt);
+    if (initialRules) return { type: 'rules', rules: initialRules };
+  }
+  if (typeof prompt === 'string') return { type: 'static', system: prompt };
+  if (prompt?.system) return { type: 'static', system: prompt.system };
+  if (prompt) throw new Error(`Agent "${config.id}": invalid prompt format`);
+  return null;
+}
+
+function normalizeTimeout(config: AgentConfig): number {
+  const timeout =
+    config.timeout === undefined || config.timeout === null || config.timeout === ''
+      ? DEFAULT_TIMEOUT
+      : Number(config.timeout);
+  config.timeout = timeout;
+  if (!Number.isFinite(timeout) || timeout < 0) {
+    throw new Error(
+      `Agent "${config.id}": timeout must be a non-negative number (got ${timeout}).`
+    );
+  }
+  return timeout;
+}
+
+function assertTestModeSafety(config: AgentConfig, options: AgentConfigOptions): void {
+  const executesTask = config.triggers?.some(
+    (trigger) => !trigger.action || trigger.action === 'execute_task'
+  );
+  if (options.testMode && !options.mockSpawnFn && !options.taskRunner && executesTask) {
+    throw new Error(
+      `AgentWrapper: testMode=true but no mockSpawnFn/taskRunner provided for agent '${config.id}'. ` +
+        `This would cause real Claude API calls. ABORTING.`
+    );
+  }
+}
+
+function validateAgentConfig(
+  config: AgentConfig,
+  options: AgentConfigOptions = {}
+): NormalizedAgentConfig {
+  applyOutputDefaults(config);
+  const modelConfig = buildModelConfig(config);
+  const settings = loadSettings();
+  const minModel = settings.minModel || null;
+  applyStrictSchemaDefault(config, settings);
+  validateModelConfig(config, modelConfig, settings.maxModel, minModel);
+  const promptConfig = buildPromptConfig(config);
+  const timeout = normalizeTimeout(config);
+  assertTestModeSafety(config, options);
+  return {
+    ...config,
+    modelConfig,
+    promptConfig,
+    maxIterations: config.maxIterations || DEFAULT_MAX_ITERATIONS,
+    timeout,
+    staleDuration: config.staleDuration || DEFAULT_STALE_DURATION_MS,
+    enableLivenessCheck: config.enableLivenessCheck ?? DEFAULT_LIVENESS_CHECK_ENABLED,
+  };
+}
+
+export = {
+  validateAgentConfig,
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_STALE_DURATION_MS,
+  DEFAULT_LIVENESS_CHECK_ENABLED,
+};

package/src/agent/agent-context-builder.js

@@ -1,278 +1,43 @@
-/**
- * AgentContextBuilder - Build agent execution context from ledger
- *
- * Provides:
- * - Context assembly from multiple message sources
- * - Context strategy evaluation (topics, limits, since timestamps)
- * - Prompt injection and formatting
- * - Token-budgeted context packs
- * - Defensive context overflow prevention
- */
-
-// Defensive limit: 500,000 chars ≈ 125k tokens (safe buffer below 200k limit)
-// Prevents "Prompt is too long" errors that kill tasks
+"use strict";
+const contextMetrics = require("./context-metrics");
+const contextPackBuilder = require("./context-pack-builder");
+const agentContextPacks = require("./agent-context-packs");
 const MAX_CONTEXT_CHARS = 500000;
-const {
-  buildContextMetrics,
-  emitContextMetrics,
-  resolveLegacyMaxTokens,
-  updateTotalMetrics,
-} = require('./context-metrics');
-const { buildContextPacks } = require('./context-pack-builder');
-const { buildSourcePack } = require('./agent-context-sources');
-const {
-  buildHeaderContext,
-  buildInstructionsSection,
-  buildJsonSchemaSection,
-  buildLegacyOutputSchemaSection,
-  buildRepoToolingSection,
-  buildTriggeringMessageSection,
-  buildValidatorSkipSection,
-} = require('./agent-context-sections');
-const { buildRequiredQualityGatesSection } = require('./agent-quality-gates-context');
-const { buildCommandProofsSection } = require('./agent-command-proofs-context');
-
-function pushStaticPack({ packs, packId, section, text, order, options = {} }) {
-  if (!text) {
-    return order;
-  }
-
-  packs.push({
-    id: packId,
-    section,
-    priority: 'required',
-    order,
-    preserve: options.preserve || false,
-    render: () => text,
-  });
-
-  return order + 1;
-}
-
-function appendSourcePacks(packs, strategy, params, startingOrder) {
-  if (!Array.isArray(strategy.sources)) {
-    return startingOrder;
-  }
-
-  let order = startingOrder;
-  strategy.sources.forEach((source, index) => {
-    packs.push({ ...buildSourcePack({ source, index, ...params }), order });
-    order += 1;
-  });
-
-  return order;
-}
-
-function buildStaticSections(params) {
-  const {
-    id,
-    role,
-    iteration,
-    config,
-    selectedPrompt,
-    queuedGuidance,
-    messageBus,
-    cluster,
-    triggeringMessage,
-    worktree,
-    isolation,
-  } = params;
-  const isIsolated = !!(worktree?.enabled || isolation?.enabled);
-
-  return {
-    header: buildHeaderContext({ id, role, iteration, isIsolated }),
-    instructions: buildInstructionsSection({ config, selectedPrompt, id }),
-    repoTooling: buildRepoToolingSection({ config, worktree }),
-    commandProofs: buildCommandProofsSection(config),
-    legacyOutputSchema: buildLegacyOutputSchemaSection(config),
-    queuedGuidance: queuedGuidance || '',
-    requiredQualityGates: buildRequiredQualityGatesSection(config),
-    jsonSchema: buildJsonSchemaSection(config),
-    validatorSkip: buildValidatorSkipSection({ role, messageBus, cluster, isolation }),
-    triggeringMessage: buildTriggeringMessageSection(triggeringMessage),
-  };
-}
-
-function buildPacks(params) {
-  const { strategy, messageBus, cluster, lastTaskEndTime, lastAgentStartTime, triggeringMessage } =
-    params;
-  const sections = buildStaticSections(params);
-  const packs = [];
-  let order = 0;
-  const staticPackIds = [
-    'header',
-    'instructions',
-    'repoTooling',
-    'commandProofs',
-    'queuedGuidance',
-    'legacyOutputSchema',
-    'requiredQualityGates',
-    'jsonSchema',
-  ];
-
-  for (const packId of staticPackIds) {
-    order = pushStaticPack({ packs, packId, section: packId, text: sections[packId], order });
-  }
-
-  order = appendSourcePacks(
-    packs,
-    strategy,
-    {
-      messageBus,
-      cluster,
-      lastTaskEndTime,
-      lastAgentStartTime,
-      throughId: params.contextThroughId,
-      triggeringMessageId: triggeringMessage?.id,
-    },
-    order
-  );
-  order = pushStaticPack({
-    packs,
-    packId: 'validatorSkip',
-    section: 'validatorSkip',
-    text: sections.validatorSkip,
-    order,
-  });
-  pushStaticPack({
-    packs,
-    packId: 'triggeringMessage',
-    section: 'triggeringMessage',
-    text: sections.triggeringMessage,
-    order,
-    options: { preserve: true },
-  });
-
-  return packs;
-}
-
-function buildContinuationPacks(params) {
-  const {
-    id,
-    iteration,
-    config,
-    selectedPrompt,
-    queuedGuidance,
-    triggeringMessage,
-    strategy,
-    messageBus,
-    cluster,
-    lastTaskEndTime,
-    lastAgentStartTime,
-    continuationSequence,
-    contextThroughId,
-    previousPromptIdentity,
-    currentPromptIdentity,
-  } = params;
-  const packs = [];
-  let order = 0;
-
-  order = pushStaticPack({
-    packs,
-    packId: 'continuationHeader',
-    section: 'continuationHeader',
-    text: `## Continuation Turn\n\nAgent: ${id}\nIteration: ${iteration}\n\nApply only the new material below while retaining the existing session instructions.\n\n`,
-    order,
-  });
-
-  // Iteration-rule prompts may intentionally change between turns. Static prompts,
-  // repository tooling, ISSUE_OPENED/PLAN_READY sources, and output contracts are
-  // already present in the provider session and must not be replayed.
-  if (config.promptConfig?.type === 'rules' && currentPromptIdentity !== previousPromptIdentity) {
-    order = pushStaticPack({
-      packs,
-      packId: 'iterationInstructions',
-      section: 'iterationInstructions',
-      text: buildInstructionsSection({ config, selectedPrompt, id }),
-      order,
-    });
-  }
-
-  order = pushStaticPack({
-    packs,
-    packId: 'queuedGuidance',
-    section: 'queuedGuidance',
-    text: queuedGuidance || '',
-    order,
-  });
-  order = appendSourcePacks(
-    packs,
-    strategy,
-    {
-      messageBus,
-      cluster,
-      lastTaskEndTime,
-      lastAgentStartTime,
-      afterId: continuationSequence,
-      throughId: contextThroughId,
-      triggeringMessageId: triggeringMessage?.id,
-    },
-    order
-  );
-  pushStaticPack({
-    packs,
-    packId: 'triggeringMessage',
-    section: 'triggeringMessage',
-    text: buildTriggeringMessageSection(triggeringMessage),
-    order,
-    options: { preserve: true },
-  });
-
-  return packs;
-}
-
-/**
- * Build execution context for an agent
- * @param {object} params - Context building parameters
- * @param {string} params.id - Agent ID
- * @param {string} params.role - Agent role
- * @param {number} params.iteration - Current iteration number
- * @param {any} params.config - Agent configuration
- * @param {any} params.messageBus - Message bus for querying ledger
- * @param {any} params.cluster - Cluster object
- * @param {number} [params.lastTaskEndTime] - Timestamp of last task completion
- * @param {number} [params.lastAgentStartTime] - Timestamp when this agent last started work
- * @param {any} params.triggeringMessage - Message that triggered this execution
- * @param {string} [params.selectedPrompt] - Pre-selected prompt from _selectPrompt() (iteration-based)
- * @param {object} [params.worktree] - Worktree isolation state (if running in worktree mode)
- * @param {object} [params.isolation] - Docker isolation state (if running in Docker mode)
- * @returns {string} Assembled context string
- */
+const { buildContextMetrics, emitContextMetrics, resolveLegacyMaxTokens, updateTotalMetrics } = contextMetrics;
+const { buildContextPacks } = contextPackBuilder;
+const { buildAgentContextPacks } = agentContextPacks;
 function buildContext(params) {
-  const strategy = params.config.contextStrategy || { sources: [] };
-  const continuation = params.mode === 'continuation';
-  const packs = continuation
-    ? buildContinuationPacks({ ...params, strategy })
-    : buildPacks({ ...params, strategy });
-  const maxTokens = resolveLegacyMaxTokens(strategy);
-  const packResult = buildContextPacks({
-    packs,
-    maxTokens,
-    maxChars: MAX_CONTEXT_CHARS,
-  });
-
-  const metrics = buildContextMetrics({
-    clusterId: params.cluster.id,
-    agentId: params.id,
-    role: params.role,
-    iteration: params.iteration,
-    triggeringMessage: params.triggeringMessage,
-    strategy: { ...strategy, contextMode: continuation ? 'continuation' : 'full' },
-    packs: packResult.packDecisions,
-    budget: packResult.budget,
-    truncation: packResult.truncation,
-  });
-
-  updateTotalMetrics(metrics, packResult.context.length);
-  emitContextMetrics(metrics, {
-    messageBus: params.messageBus,
-    clusterId: params.cluster.id,
-    agentId: params.id,
-  });
-
-  return packResult.context;
+    const strategy = params.config.contextStrategy || { sources: [] };
+    const continuation = params.mode === 'continuation';
+    const packs = buildAgentContextPacks(params, strategy, continuation);
+    const maxTokens = resolveLegacyMaxTokens(strategy);
+    const packResult = buildContextPacks({
+        packs,
+        maxTokens,
+        maxChars: MAX_CONTEXT_CHARS,
+    });
+    const metrics = buildContextMetrics({
+        clusterId: params.cluster.id,
+        agentId: params.id,
+        role: params.role,
+        iteration: params.iteration,
+        triggeringMessage: params.triggeringMessage,
+        strategy: {
+            ...strategy,
+            contextMode: continuation ? 'continuation' : 'full',
+        },
+        packs: packResult.packDecisions,
+        budget: packResult.budget,
+        truncation: packResult.truncation,
+    });
+    updateTotalMetrics(metrics, packResult.context.length);
+    emitContextMetrics(metrics, {
+        messageBus: params.messageBus,
+        clusterId: params.cluster.id,
+        agentId: params.id,
+    });
+    return packResult.context;
 }
-
 module.exports = {
-  buildContext,
+    buildContext,
 };

package/src/agent/agent-context-builder.ts

@@ -0,0 +1,51 @@
+import contextMetrics = require('./context-metrics');
+import contextPackBuilder = require('./context-pack-builder');
+import agentContextPacks = require('./agent-context-packs');
+
+import type { BuildContextParams, ContextStrategy } from './agent-context-types';
+
+const MAX_CONTEXT_CHARS = 500000;
+const { buildContextMetrics, emitContextMetrics, resolveLegacyMaxTokens, updateTotalMetrics } =
+  contextMetrics;
+const { buildContextPacks } = contextPackBuilder;
+const { buildAgentContextPacks } = agentContextPacks;
+
+function buildContext(params: BuildContextParams): string {
+  const strategy: ContextStrategy = params.config.contextStrategy || { sources: [] };
+  const continuation = params.mode === 'continuation';
+  const packs = buildAgentContextPacks(params, strategy, continuation);
+  const maxTokens = resolveLegacyMaxTokens(strategy);
+  const packResult = buildContextPacks({
+    packs,
+    maxTokens,
+    maxChars: MAX_CONTEXT_CHARS,
+  });
+
+  const metrics = buildContextMetrics({
+    clusterId: params.cluster.id,
+    agentId: params.id,
+    role: params.role,
+    iteration: params.iteration,
+    triggeringMessage: params.triggeringMessage,
+    strategy: {
+      ...strategy,
+      contextMode: continuation ? 'continuation' : 'full',
+    },
+    packs: packResult.packDecisions,
+    budget: packResult.budget,
+    truncation: packResult.truncation,
+  });
+
+  updateTotalMetrics(metrics, packResult.context.length);
+  emitContextMetrics(metrics, {
+    messageBus: params.messageBus,
+    clusterId: params.cluster.id,
+    agentId: params.id,
+  });
+
+  return packResult.context;
+}
+
+export = {
+  buildContext,
+};