@the-open-engine/zeroshot 6.38.1 → 6.39.0

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

@@ -0,0 +1,165 @@
+"use strict";
+const contextSections = require("./agent-context-sections");
+const contextSources = require("./agent-context-sources");
+const qualityGatesContext = require("./agent-quality-gates-context");
+const commandProofsContext = require("./agent-command-proofs-context");
+const { buildHeaderContext, buildInstructionsSection, buildJsonSchemaSection, buildLegacyOutputSchemaSection, buildRepoToolingSection, buildTriggeringMessageSection, buildValidatorSkipSection, } = contextSections;
+const { buildSourcePack } = contextSources;
+const { buildRequiredQualityGatesSection } = qualityGatesContext;
+const { buildCommandProofsSection } = commandProofsContext;
+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\n` +
+            'Apply only the new material below while retaining the existing session instructions.\n\n',
+        order,
+    });
+    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;
+}
+function buildAgentContextPacks(params, strategy, continuation) {
+    const contextPacksParams = { ...params, strategy };
+    return continuation ? buildContinuationPacks(contextPacksParams) : buildPacks(contextPacksParams);
+}
+module.exports = {
+    buildAgentContextPacks,
+};

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

@@ -0,0 +1,296 @@
+import contextSections = require('./agent-context-sections');
+import contextSources = require('./agent-context-sources');
+import qualityGatesContext = require('./agent-quality-gates-context');
+import commandProofsContext = require('./agent-command-proofs-context');
+
+import type {
+  BuildContextParams,
+  ContextMessageBus,
+  ContextCluster,
+  ContextStrategy,
+} from './agent-context-types';
+import type { ContextPack } from './context-pack-types';
+
+interface StaticPackOptions {
+  preserve?: boolean;
+}
+
+interface StaticPackParams {
+  packs: ContextPack[];
+  packId: string;
+  section: string;
+  text: string | null | undefined;
+  order: number;
+  options?: StaticPackOptions;
+}
+
+interface SourcePackContext {
+  messageBus: ContextMessageBus;
+  cluster: ContextCluster;
+  lastTaskEndTime?: number | null | undefined;
+  lastAgentStartTime?: number | null | undefined;
+  afterId?: unknown;
+  throughId?: unknown;
+  triggeringMessageId?: unknown;
+}
+
+interface ContextPacksParams extends BuildContextParams {
+  strategy: ContextStrategy;
+}
+
+interface StaticSections {
+  header: string;
+  instructions: string;
+  repoTooling: string;
+  commandProofs: string;
+  legacyOutputSchema: string;
+  queuedGuidance: string;
+  requiredQualityGates: string;
+  jsonSchema: string;
+  validatorSkip: string;
+  triggeringMessage: string;
+}
+
+const {
+  buildHeaderContext,
+  buildInstructionsSection,
+  buildJsonSchemaSection,
+  buildLegacyOutputSchemaSection,
+  buildRepoToolingSection,
+  buildTriggeringMessageSection,
+  buildValidatorSkipSection,
+} = contextSections;
+const { buildSourcePack } = contextSources;
+const { buildRequiredQualityGatesSection } = qualityGatesContext;
+const { buildCommandProofsSection } = commandProofsContext;
+
+function pushStaticPack({
+  packs,
+  packId,
+  section,
+  text,
+  order,
+  options = {},
+}: StaticPackParams): number {
+  if (!text) {
+    return order;
+  }
+
+  packs.push({
+    id: packId,
+    section,
+    priority: 'required',
+    order,
+    preserve: options.preserve || false,
+    render: () => text,
+  });
+
+  return order + 1;
+}
+
+function appendSourcePacks(
+  packs: ContextPack[],
+  strategy: ContextStrategy,
+  params: SourcePackContext,
+  startingOrder: number
+): number {
+  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: BuildContextParams): StaticSections {
+  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: ContextPacksParams): ContextPack[] {
+  const { strategy, messageBus, cluster, lastTaskEndTime, lastAgentStartTime, triggeringMessage } =
+    params;
+  const sections = buildStaticSections(params);
+  const packs: ContextPack[] = [];
+  let order = 0;
+  const staticPackIds: (keyof StaticSections)[] = [
+    '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: ContextPacksParams): ContextPack[] {
+  const {
+    id,
+    iteration,
+    config,
+    selectedPrompt,
+    queuedGuidance,
+    triggeringMessage,
+    strategy,
+    messageBus,
+    cluster,
+    lastTaskEndTime,
+    lastAgentStartTime,
+    continuationSequence,
+    contextThroughId,
+    previousPromptIdentity,
+    currentPromptIdentity,
+  } = params;
+  const packs: ContextPack[] = [];
+  let order = 0;
+
+  order = pushStaticPack({
+    packs,
+    packId: 'continuationHeader',
+    section: 'continuationHeader',
+    text:
+      `## Continuation Turn\n\nAgent: ${id}\nIteration: ${iteration}\n\n` +
+      'Apply only the new material below while retaining the existing session instructions.\n\n',
+    order,
+  });
+
+  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;
+}
+
+function buildAgentContextPacks(
+  params: BuildContextParams,
+  strategy: ContextStrategy,
+  continuation: boolean
+): ContextPack[] {
+  const contextPacksParams = { ...params, strategy };
+  return continuation ? buildContinuationPacks(contextPacksParams) : buildPacks(contextPacksParams);
+}
+
+export = {
+  buildAgentContextPacks,
+};

package/src/agent/agent-context-prompt-sections.js

@@ -0,0 +1,100 @@
+"use strict";
+const EXAMPLE_PRIMITIVE_VALUES = {
+    boolean: true,
+    number: 0,
+    integer: 0,
+};
+function generateExampleValue(propSchema, key) {
+    if (!propSchema) {
+        return undefined;
+    }
+    if (Array.isArray(propSchema.enum) && propSchema.enum.length > 0) {
+        return propSchema.enum[0];
+    }
+    if (propSchema.type === 'string') {
+        return propSchema.description || `${key} value`;
+    }
+    if (propSchema.type === 'array') {
+        return [];
+    }
+    if (propSchema.type === 'object') {
+        return generateExampleFromSchema(propSchema) || {};
+    }
+    return propSchema.type === undefined ? undefined : EXAMPLE_PRIMITIVE_VALUES[propSchema.type];
+}
+function generateExampleFromSchema(schema) {
+    if (!schema || schema.type !== 'object' || !schema.properties) {
+        return null;
+    }
+    const example = {};
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+        const value = generateExampleValue(propSchema, key);
+        if (value !== undefined) {
+            example[key] = value;
+        }
+    }
+    return example;
+}
+function buildInstructionsSection({ config, selectedPrompt, id, }) {
+    const promptText = selectedPrompt || (typeof config.prompt === 'string' ? config.prompt : config.prompt?.system);
+    if (promptText) {
+        return `## Instructions\n\n${promptText}\n\n`;
+    }
+    if (config.prompt && typeof config.prompt !== 'string' && !config.prompt.system) {
+        const serializedPrompt = JSON.stringify(config.prompt);
+        throw new Error(`Agent "${id}" has invalid prompt format. ` +
+            `Expected string or object with .system property, got: ${serializedPrompt.slice(0, 100)}...`);
+    }
+    return '';
+}
+function resolveLegacyOutputFormat(config) {
+    return typeof config.prompt === 'string' ? undefined : config.prompt?.outputFormat;
+}
+function buildLegacyOutputSchemaSection(config) {
+    const outputFormat = resolveLegacyOutputFormat(config);
+    if (!outputFormat) {
+        return '';
+    }
+    const rules = (outputFormat.rules || []).map((rule) => `- ${rule}`).join('\n');
+    return [
+        '## Output Schema (REQUIRED)',
+        '',
+        '```json',
+        JSON.stringify(outputFormat.example, null, 2),
+        '```',
+        '',
+        'STRING VALUES IN THIS SCHEMA: Dense. Factual. No filler words. No pleasantries.',
+        rules,
+        '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+function buildJsonSchemaSection(config) {
+    if (!config.jsonSchema || config.outputFormat !== 'json') {
+        return '';
+    }
+    const lines = [
+        '## 🔴 OUTPUT FORMAT - JSON ONLY',
+        '',
+        'Your response must be ONLY valid JSON. No other text before or after.',
+        'Start with { and end with }. Nothing else.',
+        '',
+        'Required schema:',
+        '```json',
+        JSON.stringify(config.jsonSchema, null, 2),
+        '```',
+        '',
+    ];
+    const example = generateExampleFromSchema(config.jsonSchema);
+    if (example) {
+        lines.push('Example output:', '```json', JSON.stringify(example, null, 2), '```', '');
+    }
+    lines.push('CRITICAL RULES:', '- Output ONLY the JSON object - no explanation, no thinking, no preamble', '- Use EXACTLY the enum values specified (case-sensitive)', '- Include ALL required fields', '');
+    return lines.join('\n');
+}
+module.exports = {
+    buildInstructionsSection,
+    buildJsonSchemaSection,
+    buildLegacyOutputSchemaSection,
+};

package/src/agent/agent-context-prompt-sections.ts

@@ -0,0 +1,148 @@
+import type { AgentContextConfig, JsonSchema, LegacyOutputFormat } from './agent-context-types';
+
+interface InstructionsSectionParams {
+  config: AgentContextConfig;
+  selectedPrompt?: string | null | undefined;
+  id: string;
+}
+
+const EXAMPLE_PRIMITIVE_VALUES: Readonly<Record<string, boolean | number>> = {
+  boolean: true,
+  number: 0,
+  integer: 0,
+};
+
+function generateExampleValue(propSchema: JsonSchema | null | undefined, key: string): unknown {
+  if (!propSchema) {
+    return undefined;
+  }
+
+  if (Array.isArray(propSchema.enum) && propSchema.enum.length > 0) {
+    return propSchema.enum[0];
+  }
+
+  if (propSchema.type === 'string') {
+    return propSchema.description || `${key} value`;
+  }
+
+  if (propSchema.type === 'array') {
+    return [];
+  }
+
+  if (propSchema.type === 'object') {
+    return generateExampleFromSchema(propSchema) || {};
+  }
+
+  return propSchema.type === undefined ? undefined : EXAMPLE_PRIMITIVE_VALUES[propSchema.type];
+}
+
+function generateExampleFromSchema(
+  schema: JsonSchema | null | undefined
+): Record<string, unknown> | null {
+  if (!schema || schema.type !== 'object' || !schema.properties) {
+    return null;
+  }
+
+  const example: Record<string, unknown> = {};
+
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    const value = generateExampleValue(propSchema, key);
+    if (value !== undefined) {
+      example[key] = value;
+    }
+  }
+
+  return example;
+}
+
+function buildInstructionsSection({
+  config,
+  selectedPrompt,
+  id,
+}: InstructionsSectionParams): string {
+  const promptText =
+    selectedPrompt || (typeof config.prompt === 'string' ? config.prompt : config.prompt?.system);
+
+  if (promptText) {
+    return `## Instructions\n\n${promptText}\n\n`;
+  }
+
+  if (config.prompt && typeof config.prompt !== 'string' && !config.prompt.system) {
+    const serializedPrompt = JSON.stringify(config.prompt);
+    throw new Error(
+      `Agent "${id}" has invalid prompt format. ` +
+        `Expected string or object with .system property, got: ${serializedPrompt.slice(0, 100)}...`
+    );
+  }
+
+  return '';
+}
+
+function resolveLegacyOutputFormat(
+  config: AgentContextConfig
+): LegacyOutputFormat | null | undefined {
+  return typeof config.prompt === 'string' ? undefined : config.prompt?.outputFormat;
+}
+
+function buildLegacyOutputSchemaSection(config: AgentContextConfig): string {
+  const outputFormat = resolveLegacyOutputFormat(config);
+  if (!outputFormat) {
+    return '';
+  }
+
+  const rules = (outputFormat.rules || []).map((rule) => `- ${rule}`).join('\n');
+
+  return [
+    '## Output Schema (REQUIRED)',
+    '',
+    '```json',
+    JSON.stringify(outputFormat.example, null, 2),
+    '```',
+    '',
+    'STRING VALUES IN THIS SCHEMA: Dense. Factual. No filler words. No pleasantries.',
+    rules,
+    '',
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+function buildJsonSchemaSection(config: AgentContextConfig): string {
+  if (!config.jsonSchema || config.outputFormat !== 'json') {
+    return '';
+  }
+
+  const lines = [
+    '## 🔴 OUTPUT FORMAT - JSON ONLY',
+    '',
+    'Your response must be ONLY valid JSON. No other text before or after.',
+    'Start with { and end with }. Nothing else.',
+    '',
+    'Required schema:',
+    '```json',
+    JSON.stringify(config.jsonSchema, null, 2),
+    '```',
+    '',
+  ];
+
+  const example = generateExampleFromSchema(config.jsonSchema);
+  if (example) {
+    lines.push('Example output:', '```json', JSON.stringify(example, null, 2), '```', '');
+  }
+
+  lines.push(
+    'CRITICAL RULES:',
+    '- Output ONLY the JSON object - no explanation, no thinking, no preamble',
+    '- Use EXACTLY the enum values specified (case-sensitive)',
+    '- Include ALL required fields',
+    ''
+  );
+
+  return lines.join('\n');
+}
+
+export = {
+  buildInstructionsSection,
+  buildJsonSchemaSection,
+  buildLegacyOutputSchemaSection,
+};