@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/template-validation/random-topology-contracts.ts

@@ -0,0 +1,54 @@
+import type { SimulationAgentConfig, SimulationCluster } from './simulation-agent';
+
+export type RandomNumberGenerator = () => number;
+
+export interface RandomTrigger {
+  topic: string;
+  logic?: { script?: string };
+  action?: string;
+}
+
+export interface RandomAgentConfig extends SimulationAgentConfig {
+  triggers?: RandomTrigger[];
+  hooks?: { onComplete?: unknown };
+  jsonSchema?: unknown;
+  structuredOutput?: unknown;
+  maxIterations?: number;
+}
+
+export interface RandomTemplateConfig {
+  agents?: RandomAgentConfig[];
+}
+
+export interface SimulationMessage {
+  topic: string;
+  [key: string]: unknown;
+}
+
+export interface RandomSimulationState {
+  agentConfigs: RandomAgentConfig[];
+  cluster: SimulationCluster;
+}
+
+export interface SimulationMessageBus {
+  publish(message: unknown): unknown;
+}
+
+export interface RandomDispatchContext {
+  state: RandomSimulationState;
+  messageBus: SimulationMessageBus;
+  logicEngine: unknown;
+  iterations: Map<string, number>;
+  rng: RandomNumberGenerator;
+}
+
+export type ScenarioOutcome = { ok: true } | { ok: false; reason: string };
+
+export interface RunScenarioOptions {
+  config: RandomTemplateConfig;
+  templateId: string;
+  seed: number;
+  maxSteps: number;
+  maxScenarioMs: number;
+  templatesDir: string;
+}

package/src/template-validation/random-topology-dispatch.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchScenarioMessage = dispatchScenarioMessage;
+const randomTopologyRuntime = require("./random-topology-runtime");
+const random_topology_trigger_1 = require("./random-topology-trigger");
+function isRandomTrigger(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'topic' in value &&
+        typeof value.topic === 'string');
+}
+async function dispatchScenarioMessage(context, message) {
+    for (const agentConfig of context.state.agentConfigs) {
+        const triggerValue = randomTopologyRuntime.findMatchingTrigger({
+            triggers: agentConfig.triggers || [],
+            message,
+        });
+        if (!isRandomTrigger(triggerValue))
+            continue;
+        const outcome = await (0, random_topology_trigger_1.executeAgentTrigger)(context, agentConfig, triggerValue, message);
+        if (outcome)
+            return outcome;
+    }
+    return null;
+}

package/src/template-validation/random-topology-dispatch.ts

@@ -0,0 +1,33 @@
+import type {
+  RandomDispatchContext,
+  RandomTrigger,
+  ScenarioOutcome,
+  SimulationMessage,
+} from './random-topology-contracts';
+import randomTopologyRuntime = require('./random-topology-runtime');
+import { executeAgentTrigger } from './random-topology-trigger';
+
+function isRandomTrigger(value: unknown): value is RandomTrigger {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'topic' in value &&
+    typeof value.topic === 'string'
+  );
+}
+
+export async function dispatchScenarioMessage(
+  context: RandomDispatchContext,
+  message: SimulationMessage
+): Promise<ScenarioOutcome | null> {
+  for (const agentConfig of context.state.agentConfigs) {
+    const triggerValue = randomTopologyRuntime.findMatchingTrigger({
+      triggers: agentConfig.triggers || [],
+      message,
+    });
+    if (!isRandomTrigger(triggerValue)) continue;
+    const outcome = await executeAgentTrigger(context, agentConfig, triggerValue, message);
+    if (outcome) return outcome;
+  }
+  return null;
+}

package/src/template-validation/random-topology-message-loop.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMessageLoop = runMessageLoop;
+const random_topology_dispatch_1 = require("./random-topology-dispatch");
+const random_topology_operations_1 = require("./random-topology-operations");
+function isSimulationMessage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'topic' in value &&
+        typeof value.topic === 'string');
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function processMessage(context, message) {
+    if (message.topic === 'CLUSTER_COMPLETE')
+        return Promise.resolve({ ok: true });
+    if (message.topic === 'CLUSTER_FAILED') {
+        return Promise.resolve({ ok: false, reason: 'scenario reached CLUSTER_FAILED' });
+    }
+    if (message.topic === 'CLUSTER_OPERATIONS') {
+        try {
+            (0, random_topology_operations_1.handleClusterOperationsMessage)(context.state, context.messageBus, message, context.templatesDir);
+            return Promise.resolve(null);
+        }
+        catch (error) {
+            return Promise.resolve({
+                ok: false,
+                reason: `invalid CLUSTER_OPERATIONS: ${errorMessage(error)}`,
+            });
+        }
+    }
+    return (0, random_topology_dispatch_1.dispatchScenarioMessage)(context, message);
+}
+async function runMessageLoop(context) {
+    let stepCount = 0;
+    while (context.queue.length > 0) {
+        if (Date.now() - context.startedAt > context.maxScenarioMs) {
+            return { ok: false, reason: `scenario timed out after ${context.maxScenarioMs}ms` };
+        }
+        if (stepCount >= context.maxSteps) {
+            return { ok: false, reason: `scenario exceeded step budget (${context.maxSteps})` };
+        }
+        stepCount += 1;
+        const messageValue = context.queue.shift();
+        if (!isSimulationMessage(messageValue))
+            continue;
+        const outcome = await processMessage(context, messageValue);
+        if (outcome)
+            return outcome;
+    }
+    return { ok: false, reason: 'message flow quiesced without CLUSTER_COMPLETE' };
+}

package/src/template-validation/random-topology-message-loop.ts

@@ -0,0 +1,73 @@
+import type {
+  RandomDispatchContext,
+  ScenarioOutcome,
+  SimulationMessage,
+} from './random-topology-contracts';
+import { dispatchScenarioMessage } from './random-topology-dispatch';
+import { handleClusterOperationsMessage } from './random-topology-operations';
+
+export interface MessageLoopContext extends RandomDispatchContext {
+  queue: unknown[];
+  templatesDir: string;
+  startedAt: number;
+  maxSteps: number;
+  maxScenarioMs: number;
+}
+
+function isSimulationMessage(value: unknown): value is SimulationMessage {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'topic' in value &&
+    typeof value.topic === 'string'
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function processMessage(
+  context: MessageLoopContext,
+  message: SimulationMessage
+): Promise<ScenarioOutcome | null> {
+  if (message.topic === 'CLUSTER_COMPLETE') return Promise.resolve({ ok: true });
+  if (message.topic === 'CLUSTER_FAILED') {
+    return Promise.resolve({ ok: false, reason: 'scenario reached CLUSTER_FAILED' });
+  }
+  if (message.topic === 'CLUSTER_OPERATIONS') {
+    try {
+      handleClusterOperationsMessage(
+        context.state,
+        context.messageBus,
+        message,
+        context.templatesDir
+      );
+      return Promise.resolve(null);
+    } catch (error) {
+      return Promise.resolve({
+        ok: false,
+        reason: `invalid CLUSTER_OPERATIONS: ${errorMessage(error)}`,
+      });
+    }
+  }
+  return dispatchScenarioMessage(context, message);
+}
+
+export async function runMessageLoop(context: MessageLoopContext): Promise<ScenarioOutcome> {
+  let stepCount = 0;
+  while (context.queue.length > 0) {
+    if (Date.now() - context.startedAt > context.maxScenarioMs) {
+      return { ok: false, reason: `scenario timed out after ${context.maxScenarioMs}ms` };
+    }
+    if (stepCount >= context.maxSteps) {
+      return { ok: false, reason: `scenario exceeded step budget (${context.maxSteps})` };
+    }
+    stepCount += 1;
+    const messageValue = context.queue.shift();
+    if (!isSimulationMessage(messageValue)) continue;
+    const outcome = await processMessage(context, messageValue);
+    if (outcome) return outcome;
+  }
+  return { ok: false, reason: 'message flow quiesced without CLUSTER_COMPLETE' };
+}

package/src/template-validation/random-topology-operations.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleClusterOperationsMessage = handleClusterOperationsMessage;
+const randomTopologyRuntime = require("./random-topology-runtime");
+const random_topology_state_1 = require("./random-topology-state");
+function parseOperations(raw) {
+    if (Array.isArray(raw))
+        return raw.map((operation) => operation);
+    if (typeof raw === 'string') {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.map((operation) => operation) : null;
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function resolveConfigOperation(configOperation, templatesDir) {
+    const resolver = new randomTopologyRuntime.TemplateResolver(templatesDir);
+    const resolved = resolver.resolveConfigReference(configOperation);
+    if (!isRecord(resolved) || !isRecord(resolved.loadedConfig)) {
+        throw new TypeError('TemplateResolver returned an invalid loadedConfig');
+    }
+    return resolved.loadedConfig;
+}
+function publishOperation(state, messageBus, operation, sourceMessage) {
+    messageBus.publish({
+        cluster_id: state.cluster.id,
+        topic: operation.topic,
+        sender: '__sim_orchestrator__',
+        receiver: operation.receiver || 'broadcast',
+        content: operation.content || {},
+        metadata: operation.metadata || { fromTopic: sourceMessage.topic },
+    });
+}
+function applyClusterOperation(options) {
+    const { state, messageBus, operation: operationValue, sourceMessage, templatesDir } = options;
+    if (!isRecord(operationValue) || !operationValue.action)
+        return;
+    const operation = operationValue;
+    if (operation.action === 'load_config') {
+        (0, random_topology_state_1.addAgentsToState)(state, resolveConfigOperation(operation.config, templatesDir).agents);
+    }
+    else if (operation.action === 'add_agents') {
+        (0, random_topology_state_1.addAgentsToState)(state, operation.agents);
+    }
+    else if (operation.action === 'remove_agents') {
+        const ids = new Set(operationAgentIds(operation.agentIds));
+        state.agentConfigs = state.agentConfigs.filter((agent) => !ids.has(agent.id));
+        state.cluster.agents = state.cluster.agents.filter((agent) => !ids.has(agent.id));
+    }
+    else if (operation.action === 'update_agent') {
+        const target = state.agentConfigs.find((agent) => agent.id === operation.agentId);
+        if (target && isRecord(operation.updates))
+            Object.assign(target, operation.updates);
+    }
+    else if (operation.action === 'publish') {
+        publishOperation(state, messageBus, operation, sourceMessage);
+    }
+}
+function operationAgentIds(value) {
+    return Array.isArray(value) ? value : [];
+}
+function operationsValue(message) {
+    const content = message.content;
+    if (!isRecord(content) || !isRecord(content.data))
+        return undefined;
+    return content.data.operations;
+}
+function handleClusterOperationsMessage(state, messageBus, message, templatesDir) {
+    const raw = operationsValue(message);
+    const operations = parseOperations(raw);
+    if (!operations) {
+        throw new Error(`CLUSTER_OPERATIONS missing operations array: ${JSON.stringify(raw)}`);
+    }
+    for (const operation of operations) {
+        applyClusterOperation({ state, messageBus, operation, sourceMessage: message, templatesDir });
+    }
+}

package/src/template-validation/random-topology-operations.ts

@@ -0,0 +1,101 @@
+import randomTopologyRuntime = require('./random-topology-runtime');
+import type {
+  RandomSimulationState,
+  SimulationMessage,
+  SimulationMessageBus,
+} from './random-topology-contracts';
+import { addAgentsToState } from './random-topology-state';
+
+type UnknownRecord = Record<string, unknown>;
+
+function parseOperations(raw: unknown): unknown[] | null {
+  if (Array.isArray(raw)) return raw.map((operation: unknown) => operation);
+  if (typeof raw === 'string') {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.map((operation: unknown) => operation) : null;
+  }
+  return null;
+}
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function resolveConfigOperation(configOperation: unknown, templatesDir: string): UnknownRecord {
+  const resolver = new randomTopologyRuntime.TemplateResolver(templatesDir);
+  const resolved = resolver.resolveConfigReference(configOperation);
+  if (!isRecord(resolved) || !isRecord(resolved.loadedConfig)) {
+    throw new TypeError('TemplateResolver returned an invalid loadedConfig');
+  }
+  return resolved.loadedConfig;
+}
+
+interface ApplyOperationOptions {
+  state: RandomSimulationState;
+  messageBus: SimulationMessageBus;
+  operation: unknown;
+  sourceMessage: SimulationMessage;
+  templatesDir: string;
+}
+
+function publishOperation(
+  state: RandomSimulationState,
+  messageBus: SimulationMessageBus,
+  operation: UnknownRecord,
+  sourceMessage: SimulationMessage
+): void {
+  messageBus.publish({
+    cluster_id: state.cluster.id,
+    topic: operation.topic,
+    sender: '__sim_orchestrator__',
+    receiver: operation.receiver || 'broadcast',
+    content: operation.content || {},
+    metadata: operation.metadata || { fromTopic: sourceMessage.topic },
+  });
+}
+
+function applyClusterOperation(options: ApplyOperationOptions): void {
+  const { state, messageBus, operation: operationValue, sourceMessage, templatesDir } = options;
+  if (!isRecord(operationValue) || !operationValue.action) return;
+  const operation = operationValue;
+  if (operation.action === 'load_config') {
+    addAgentsToState(state, resolveConfigOperation(operation.config, templatesDir).agents);
+  } else if (operation.action === 'add_agents') {
+    addAgentsToState(state, operation.agents);
+  } else if (operation.action === 'remove_agents') {
+    const ids = new Set(operationAgentIds(operation.agentIds));
+    state.agentConfigs = state.agentConfigs.filter((agent) => !ids.has(agent.id));
+    state.cluster.agents = state.cluster.agents.filter((agent) => !ids.has(agent.id));
+  } else if (operation.action === 'update_agent') {
+    const target = state.agentConfigs.find((agent) => agent.id === operation.agentId);
+    if (target && isRecord(operation.updates)) Object.assign(target, operation.updates);
+  } else if (operation.action === 'publish') {
+    publishOperation(state, messageBus, operation, sourceMessage);
+  }
+}
+
+function operationAgentIds(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function operationsValue(message: SimulationMessage): unknown {
+  const content = message.content;
+  if (!isRecord(content) || !isRecord(content.data)) return undefined;
+  return content.data.operations;
+}
+
+export function handleClusterOperationsMessage(
+  state: RandomSimulationState,
+  messageBus: SimulationMessageBus,
+  message: SimulationMessage,
+  templatesDir: string
+): void {
+  const raw = operationsValue(message);
+  const operations = parseOperations(raw);
+  if (!operations) {
+    throw new Error(`CLUSTER_OPERATIONS missing operations array: ${JSON.stringify(raw)}`);
+  }
+  for (const operation of operations) {
+    applyClusterOperation({ state, messageBus, operation, sourceMessage: message, templatesDir });
+  }
+}

package/src/template-validation/random-topology-runtime.js

@@ -0,0 +1,25 @@
+"use strict";
+function isTemplateResolverConstructor(value) {
+    return typeof value === 'function';
+}
+function isTriggerEvaluatorModule(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'findMatchingTrigger' in value &&
+        typeof value.findMatchingTrigger === 'function' &&
+        'evaluateTrigger' in value &&
+        typeof value.evaluateTrigger === 'function');
+}
+const templateResolverModule = require('../template-resolver');
+const triggerEvaluatorModule = require('../agent/agent-trigger-evaluator');
+if (!isTemplateResolverConstructor(templateResolverModule)) {
+    throw new TypeError('template-resolver must export a constructor');
+}
+if (!isTriggerEvaluatorModule(triggerEvaluatorModule)) {
+    throw new TypeError('agent-trigger-evaluator must export trigger functions');
+}
+module.exports = {
+    TemplateResolver: templateResolverModule,
+    findMatchingTrigger: triggerEvaluatorModule.findMatchingTrigger,
+    evaluateTrigger: triggerEvaluatorModule.evaluateTrigger,
+};

package/src/template-validation/random-topology-runtime.ts

@@ -0,0 +1,43 @@
+interface TemplateResolverInstance {
+  resolveConfigReference(configOperation: unknown): unknown;
+}
+
+interface TemplateResolverConstructor {
+  new (templatesDirectory: string): TemplateResolverInstance;
+}
+
+interface TriggerEvaluatorModule {
+  findMatchingTrigger(options: unknown): unknown;
+  evaluateTrigger(options: unknown): boolean;
+}
+
+function isTemplateResolverConstructor(value: unknown): value is TemplateResolverConstructor {
+  return typeof value === 'function';
+}
+
+function isTriggerEvaluatorModule(value: unknown): value is TriggerEvaluatorModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'findMatchingTrigger' in value &&
+    typeof value.findMatchingTrigger === 'function' &&
+    'evaluateTrigger' in value &&
+    typeof value.evaluateTrigger === 'function'
+  );
+}
+
+const templateResolverModule: unknown = require('../template-resolver');
+const triggerEvaluatorModule: unknown = require('../agent/agent-trigger-evaluator');
+
+if (!isTemplateResolverConstructor(templateResolverModule)) {
+  throw new TypeError('template-resolver must export a constructor');
+}
+if (!isTriggerEvaluatorModule(triggerEvaluatorModule)) {
+  throw new TypeError('agent-trigger-evaluator must export trigger functions');
+}
+
+export = {
+  TemplateResolver: templateResolverModule,
+  findMatchingTrigger: triggerEvaluatorModule.findMatchingTrigger,
+  evaluateTrigger: triggerEvaluatorModule.evaluateTrigger,
+};

package/src/template-validation/random-topology-scenario.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runScenario = runScenario;
+const random_topology_message_loop_1 = require("./random-topology-message-loop");
+const random_topology_schema_1 = require("./random-topology-schema");
+const random_topology_state_1 = require("./random-topology-state");
+const simulationRuntime = require("./simulation-runtime");
+function createIssueOpenedMessage(clusterId) {
+    return {
+        cluster_id: clusterId,
+        topic: 'ISSUE_OPENED',
+        sender: 'system',
+        receiver: 'broadcast',
+        content: { text: 'template validation simulation', data: {} },
+    };
+}
+function createState(options) {
+    const agentConfigs = (0, random_topology_state_1.cloneAgentConfigs)(options.config.agents || []);
+    return {
+        agentConfigs,
+        cluster: {
+            id: `sim-${options.templateId}-${options.seed}`,
+            agents: agentConfigs.map((agent) => ({ id: agent.id, role: agent.role })),
+        },
+    };
+}
+async function runScenario(options) {
+    const state = createState(options);
+    const runtime = simulationRuntime.createSimulationRuntime(state.cluster);
+    const queue = [];
+    const unsubscribe = runtime.messageBus.subscribe((message) => queue.push(message));
+    const startedAt = Date.now();
+    try {
+        runtime.messageBus.publish(createIssueOpenedMessage(state.cluster.id));
+        return await (0, random_topology_message_loop_1.runMessageLoop)({
+            state,
+            messageBus: runtime.messageBus,
+            logicEngine: runtime.logicEngine,
+            iterations: new Map(),
+            rng: (0, random_topology_schema_1.createSeededRng)(options.seed),
+            queue,
+            templatesDir: options.templatesDir,
+            startedAt,
+            maxSteps: options.maxSteps,
+            maxScenarioMs: options.maxScenarioMs,
+        });
+    }
+    finally {
+        unsubscribe();
+        runtime.ledger.close();
+    }
+}

package/src/template-validation/random-topology-scenario.ts

@@ -0,0 +1,57 @@
+import type {
+  RandomSimulationState,
+  RunScenarioOptions,
+  ScenarioOutcome,
+  SimulationMessage,
+} from './random-topology-contracts';
+import { runMessageLoop } from './random-topology-message-loop';
+import { createSeededRng } from './random-topology-schema';
+import { cloneAgentConfigs } from './random-topology-state';
+import simulationRuntime = require('./simulation-runtime');
+
+function createIssueOpenedMessage(clusterId: string): SimulationMessage {
+  return {
+    cluster_id: clusterId,
+    topic: 'ISSUE_OPENED',
+    sender: 'system',
+    receiver: 'broadcast',
+    content: { text: 'template validation simulation', data: {} },
+  };
+}
+
+function createState(options: RunScenarioOptions): RandomSimulationState {
+  const agentConfigs = cloneAgentConfigs(options.config.agents || []);
+  return {
+    agentConfigs,
+    cluster: {
+      id: `sim-${options.templateId}-${options.seed}`,
+      agents: agentConfigs.map((agent) => ({ id: agent.id, role: agent.role })),
+    },
+  };
+}
+
+export async function runScenario(options: RunScenarioOptions): Promise<ScenarioOutcome> {
+  const state = createState(options);
+  const runtime = simulationRuntime.createSimulationRuntime(state.cluster);
+  const queue: unknown[] = [];
+  const unsubscribe = runtime.messageBus.subscribe((message) => queue.push(message));
+  const startedAt = Date.now();
+  try {
+    runtime.messageBus.publish(createIssueOpenedMessage(state.cluster.id));
+    return await runMessageLoop({
+      state,
+      messageBus: runtime.messageBus,
+      logicEngine: runtime.logicEngine,
+      iterations: new Map(),
+      rng: createSeededRng(options.seed),
+      queue,
+      templatesDir: options.templatesDir,
+      startedAt,
+      maxSteps: options.maxSteps,
+      maxScenarioMs: options.maxScenarioMs,
+    });
+  } finally {
+    unsubscribe();
+    runtime.ledger.close();
+  }
+}