@the-open-engine/zeroshot 5.4.0

package/src/agent/agent-config.js

@@ -0,0 +1,266 @@
+/**
+ * AgentConfig - Agent configuration validation and defaults
+ *
+ * Provides:
+ * - Config validation and normalization
+ * - Default values for optional fields
+ * - Model configuration setup
+ * - Safety checks for test mode
+ * - maxModel ceiling enforcement at config time
+ */
+
+const { loadSettings, validateModelAgainstMax, VALID_MODELS } = require('../../lib/settings');
+const { applyValidatorQualityGateDefaults } = require('./agent-quality-gate-schema');
+
+const VALID_LEVELS = ['level1', 'level2', 'level3'];
+
+// Default max iterations (high limit - let the user decide when to give up)
+const DEFAULT_MAX_ITERATIONS = 100;
+
+// Default timeout: 0 = no timeout (task runs until completion or explicit kill)
+// Use positive number for timeout in milliseconds
+const DEFAULT_TIMEOUT = 0;
+
+// Stale detection - ENABLED by default using multi-indicator analysis (safe from false positives)
+// Multi-indicator approach checks: process state, CPU usage, context switches, network I/O
+// Only flags as stuck when ALL indicators show inactivity (score >= 3.5)
+// Single-indicator detection (just output freshness) was too risky - this is safe.
+const DEFAULT_STALE_DURATION_MS = 30 * 60 * 1000; // 30 minutes before triggering analysis
+const DEFAULT_LIVENESS_CHECK_ENABLED = true; // Safe with multi-indicator detection
+
+function applyOutputDefaults(config) {
+  // CRITICAL: Enforce JSON schema output by default to prevent parse failures and crashes
+  if (!config.outputFormat) {
+    config.outputFormat = 'json';
+  }
+
+  // Map structuredOutput → jsonSchema (structuredOutput is the user-facing API name,
+  // jsonSchema is the internal key used by task executor and CLI args).
+  // Explicit jsonSchema takes precedence over structuredOutput.
+  if (config.structuredOutput && !config.jsonSchema) {
+    config.jsonSchema = config.structuredOutput;
+  }
+
+  // If outputFormat is json but no schema defined, use a minimal default schema
+  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) {
+  if (config.modelRules) {
+    return { type: 'rules', rules: config.modelRules };
+  }
+  return {
+    type: 'static',
+    model: config.model || null,
+    modelLevel: config.modelLevel || null,
+  };
+}
+
+function applyStrictSchemaDefault(config, settings) {
+  if (config.strictSchema === undefined) {
+    config.strictSchema = settings.strictSchema !== false; // Default true if not set
+  }
+}
+
+function validateStaticModelConfig(configId, modelConfig, maxModel, minModel) {
+  if (modelConfig.model && VALID_MODELS.includes(modelConfig.model)) {
+    try {
+      validateModelAgainstMax(modelConfig.model, maxModel, minModel);
+    } catch (error) {
+      throw new Error(`Agent "${configId}": ${error.message}`);
+    }
+  }
+
+  if (modelConfig.modelLevel && !VALID_LEVELS.includes(modelConfig.modelLevel)) {
+    throw new Error(
+      `Agent "${configId}": invalid modelLevel "${modelConfig.modelLevel}". ` +
+        `Valid: ${VALID_LEVELS.join(', ')}`
+    );
+  }
+}
+
+function validateModelRule(configId, rule, maxModel, minModel) {
+  if (rule.model && VALID_MODELS.includes(rule.model)) {
+    try {
+      validateModelAgainstMax(rule.model, maxModel, minModel);
+    } catch {
+      throw new Error(
+        `Agent "${configId}": modelRule "${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 && !VALID_LEVELS.includes(rule.modelLevel)) {
+    throw new Error(
+      `Agent "${configId}": modelRule "${rule.iterations}" has invalid modelLevel ` +
+        `"${rule.modelLevel}". Valid: ${VALID_LEVELS.join(', ')}`
+    );
+  }
+}
+
+function validateModelConfig(config, modelConfig, maxModel, minModel) {
+  if (modelConfig.type === 'static') {
+    validateStaticModelConfig(config.id, modelConfig, maxModel, minModel);
+    return;
+  }
+
+  if (modelConfig.type === 'rules') {
+    for (const rule of modelConfig.rules) {
+      validateModelRule(config.id, rule, maxModel, minModel);
+    }
+  }
+}
+
+function buildInitialPromptRules(prompt) {
+  if (prompt?.initial || prompt?.subsequent) {
+    const rules = [];
+    if (prompt.initial) rules.push({ match: '1', system: prompt.initial });
+    if (prompt.subsequent) rules.push({ match: '2+', system: prompt.subsequent });
+    return rules;
+  }
+
+  return null;
+}
+
+function buildPromptConfig(config) {
+  const prompt = config.prompt;
+  if (prompt?.iterations) {
+    return { type: 'rules', rules: prompt.iterations };
+  }
+
+  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) {
+  if (config.timeout === undefined || config.timeout === null || config.timeout === '') {
+    config.timeout = DEFAULT_TIMEOUT;
+  } else {
+    config.timeout = Number(config.timeout);
+  }
+
+  if (!Number.isFinite(config.timeout) || config.timeout < 0) {
+    throw new Error(
+      `Agent "${config.id}": timeout must be a non-negative number (got ${config.timeout}).`
+    );
+  }
+
+  return config.timeout;
+}
+
+function buildNormalizedConfig(config, modelConfig, promptConfig) {
+  return {
+    ...config,
+    modelConfig,
+    promptConfig,
+    maxIterations: config.maxIterations || DEFAULT_MAX_ITERATIONS,
+    timeout: config.timeout,
+    staleDuration: config.staleDuration || DEFAULT_STALE_DURATION_MS,
+    enableLivenessCheck: config.enableLivenessCheck ?? DEFAULT_LIVENESS_CHECK_ENABLED,
+  };
+}
+
+function assertTestModeSafety(config, options) {
+  const executesTask = config.triggers?.some(
+    (trigger) => !trigger.action || trigger.action === 'execute_task'
+  );
+  const hasMock = options.mockSpawnFn || options.taskRunner;
+
+  if (options.testMode && !hasMock && executesTask) {
+    throw new Error(
+      `AgentWrapper: testMode=true but no mockSpawnFn/taskRunner provided for agent '${config.id}'. ` +
+        `This would cause real Claude API calls. ABORTING.`
+    );
+  }
+}
+
+/**
+ * Validate and normalize agent configuration
+ * @param {Object} config - Raw agent configuration
+ * @param {Object} options - Agent wrapper options
+ * @returns {Object} Normalized configuration
+ */
+function validateAgentConfig(config, options = {}) {
+  applyOutputDefaults(config);
+
+  // Model configuration: support both static model and dynamic rules
+  // If no model specified, model is null - _selectModel() will use provider defaults
+  const modelConfig = buildModelConfig(config);
+
+  // COST CEILING/FLOOR ENFORCEMENT: Validate model(s) against maxModel and minModel at config time
+  // Catches violations EARLY (config load) instead of at runtime (iteration N)
+  const settings = loadSettings();
+  const maxModel = settings.maxModel;
+  const minModel = settings.minModel || null;
+
+  // STRICT SCHEMA PROPAGATION: Issue #52 fix
+  // If agent config doesn't explicitly set strictSchema, inherit from global settings
+  // This allows `zeroshot settings set strictSchema false` to actually affect agents
+  // Default behavior: strictSchema=true (reliable JSON output, no streaming)
+  applyStrictSchemaDefault(config, settings);
+  validateModelConfig(config, modelConfig, maxModel, minModel);
+
+  // Prompt configuration: support static prompt OR iteration-based rules
+  // Formats:
+  //   prompt: "string"                              -> static
+  //   prompt: { system: "string" }                  -> static
+  //   prompt: { initial: "...", subsequent: "..." } -> iteration 1 vs 2+
+  //   prompt: { iterations: [...] }                 -> full control
+  const promptConfig = buildPromptConfig(config);
+
+  // Default timeout to 0 (no timeout) if not specified
+  // Use positive number for timeout in milliseconds
+  // ROBUST: Handle undefined, null, AND string values from template resolution
+  normalizeTimeout(config);
+
+  // Build normalized config
+  const normalizedConfig = buildNormalizedConfig(config, modelConfig, promptConfig);
+
+  // SAFETY: In test mode, verify mock is provided for agents that execute tasks
+  // Check if this agent executes tasks (vs orchestrator agents that only publish messages)
+  assertTestModeSafety(config, options);
+
+  return normalizedConfig;
+}
+
+module.exports = {
+  validateAgentConfig,
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_STALE_DURATION_MS,
+  DEFAULT_LIVENESS_CHECK_ENABLED,
+};

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

@@ -0,0 +1,189 @@
+/**
+ * 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
+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');
+
+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 }),
+    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 } = params;
+  const sections = buildStaticSections(params);
+  const packs = [];
+  let order = 0;
+  const staticPackIds = [
+    'header',
+    'instructions',
+    'repoTooling',
+    '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 },
+    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;
+}
+
+/**
+ * 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
+ */
+function buildContext(params) {
+  const strategy = params.config.contextStrategy || { sources: [] };
+  const packs = 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,
+    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,
+};