@the-open-engine/zeroshot 6.38.0 → 6.39.0

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

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSeededRng = createSeededRng;
+exports.sampleFromSchema = sampleFromSchema;
+exports.sampleResultData = sampleResultData;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function createSeededRng(seed) {
+    let state = seed >>> 0 || 0x9e3779b9;
+    return () => {
+        state ^= state << 13;
+        state >>>= 0;
+        state ^= state >>> 17;
+        state >>>= 0;
+        state ^= state << 5;
+        state >>>= 0;
+        return state / 4_294_967_296;
+    };
+}
+function randomInt(rng, min, max) {
+    if (!Number.isFinite(min) || !Number.isFinite(max)) {
+        return 0;
+    }
+    if (max <= min) {
+        return Math.round(min);
+    }
+    return Math.floor(rng() * (max - min + 1)) + min;
+}
+function randomPick(rng, values, fallback) {
+    if (values.length === 0) {
+        return fallback;
+    }
+    return values[randomInt(rng, 0, values.length - 1)];
+}
+function normalizeType(schema) {
+    if (!schema.type)
+        return null;
+    if (Array.isArray(schema.type)) {
+        return schema.type[0] ?? null;
+    }
+    return schema.type;
+}
+function sampleString(schema, rng) {
+    const candidates = stringCandidates(schema);
+    let value = randomPick(rng, candidates, 'sample');
+    if (value === undefined)
+        value = 'sample';
+    const minLength = Number.isInteger(schema.minLength) ? Number(schema.minLength) : 0;
+    const maxLength = Number.isInteger(schema.maxLength) ? Number(schema.maxLength) : value.length;
+    while (value.length < minLength)
+        value += 'x';
+    if (maxLength >= 0 && value.length > maxLength)
+        value = value.slice(0, maxLength);
+    if (!value && minLength > 0)
+        value = 'x'.repeat(minLength);
+    return value;
+}
+function stringCandidates(schema) {
+    const candidates = [];
+    if (typeof schema.default === 'string')
+        candidates.push(schema.default);
+    if (typeof schema.description === 'string')
+        candidates.push(schema.description);
+    candidates.push('sample', 'ok', 'done', 'pass', 'fail');
+    return candidates;
+}
+function finiteNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function sampleNumber(schema, rng, asInteger) {
+    const minimum = finiteNumber(schema.minimum, 0);
+    const maximum = finiteNumber(schema.maximum, 10);
+    if (maximum < minimum) {
+        return asInteger ? Math.round(minimum) : minimum;
+    }
+    if (asInteger) {
+        return randomInt(rng, Math.ceil(minimum), Math.floor(maximum));
+    }
+    return minimum + (maximum - minimum) * rng();
+}
+function sampleArray(schema, rng, depth) {
+    const minItems = Number.isInteger(schema.minItems) ? Number(schema.minItems) : 0;
+    const rawMaximum = Number.isInteger(schema.maxItems) ? Number(schema.maxItems) : minItems + 2;
+    const maxItems = Math.max(minItems, Math.min(rawMaximum, 3));
+    const length = randomInt(rng, minItems, maxItems);
+    const itemsSchema = Array.isArray(schema.items)
+        ? randomPick(rng, schema.items, {})
+        : schema.items || {};
+    const values = [];
+    for (let index = 0; index < length; index += 1) {
+        values.push(sampleFromSchema(itemsSchema, rng, depth + 1));
+    }
+    return values;
+}
+function sampleObject(schema, rng, depth) {
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const value = {};
+    for (const [key, propertySchema] of Object.entries(properties)) {
+        value[key] = sampleFromSchema(propertySchema, rng, depth + 1);
+    }
+    return value;
+}
+function isNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+function sampleSchemaKeyword(schema, rng, depth) {
+    if (schema.const !== undefined)
+        return { matched: true, value: schema.const };
+    if (isNonEmptyArray(schema.enum)) {
+        return { matched: true, value: randomPick(rng, schema.enum, null) };
+    }
+    if (isNonEmptyArray(schema.oneOf)) {
+        const selected = randomPick(rng, schema.oneOf, null);
+        return { matched: true, value: sampleFromSchema(selected, rng, depth + 1) };
+    }
+    if (isNonEmptyArray(schema.anyOf)) {
+        const selected = randomPick(rng, schema.anyOf, null);
+        return { matched: true, value: sampleFromSchema(selected, rng, depth + 1) };
+    }
+    if (isNonEmptyArray(schema.allOf)) {
+        return { matched: true, value: sampleFromSchema(schema.allOf[0], rng, depth + 1) };
+    }
+    return { matched: false };
+}
+function sampleSchemaType(schema, rng, depth) {
+    const type = normalizeType(schema);
+    if (type === 'boolean')
+        return { matched: true, value: rng() >= 0.5 };
+    if (type === 'integer')
+        return { matched: true, value: sampleNumber(schema, rng, true) };
+    if (type === 'number')
+        return { matched: true, value: sampleNumber(schema, rng, false) };
+    if (type === 'array')
+        return { matched: true, value: sampleArray(schema, rng, depth) };
+    if (type === 'object' || schema.properties) {
+        return { matched: true, value: sampleObject(schema, rng, depth) };
+    }
+    return { matched: false };
+}
+function sampleFromSchema(schemaValue, rng, depth = 0) {
+    if (!isRecord(schemaValue) || depth > 4) {
+        return null;
+    }
+    const keyword = sampleSchemaKeyword(schemaValue, rng, depth);
+    if (keyword.matched)
+        return keyword.value;
+    const typed = sampleSchemaType(schemaValue, rng, depth);
+    if (typed.matched)
+        return typed.value;
+    return sampleString(schemaValue, rng);
+}
+function sampleResultData(agentConfig, rng) {
+    const schema = agentConfig.jsonSchema || agentConfig.structuredOutput || null;
+    if (schema) {
+        return sampleFromSchema(schema, rng);
+    }
+    return { summary: 'sample', result: 'sample' };
+}

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

@@ -0,0 +1,190 @@
+import type { RandomAgentConfig, RandomNumberGenerator } from './random-topology-contracts';
+
+type SchemaRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is SchemaRecord {
+  return typeof value === 'object' && value !== null;
+}
+
+export function createSeededRng(seed: number): RandomNumberGenerator {
+  let state = seed >>> 0 || 0x9e3779b9;
+  return () => {
+    state ^= state << 13;
+    state >>>= 0;
+    state ^= state >>> 17;
+    state >>>= 0;
+    state ^= state << 5;
+    state >>>= 0;
+    return state / 4_294_967_296;
+  };
+}
+
+function randomInt(rng: RandomNumberGenerator, min: number, max: number): number {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    return 0;
+  }
+  if (max <= min) {
+    return Math.round(min);
+  }
+  return Math.floor(rng() * (max - min + 1)) + min;
+}
+
+function randomPick<T>(
+  rng: RandomNumberGenerator,
+  values: readonly T[],
+  fallback: T
+): T | undefined {
+  if (values.length === 0) {
+    return fallback;
+  }
+  return values[randomInt(rng, 0, values.length - 1)];
+}
+
+function normalizeType(schema: SchemaRecord): unknown {
+  if (!schema.type) return null;
+  if (Array.isArray(schema.type)) {
+    return schema.type[0] ?? null;
+  }
+  return schema.type;
+}
+
+function sampleString(schema: SchemaRecord, rng: RandomNumberGenerator): string {
+  const candidates = stringCandidates(schema);
+  let value = randomPick(rng, candidates, 'sample');
+  if (value === undefined) value = 'sample';
+
+  const minLength = Number.isInteger(schema.minLength) ? Number(schema.minLength) : 0;
+  const maxLength = Number.isInteger(schema.maxLength) ? Number(schema.maxLength) : value.length;
+
+  while (value.length < minLength) value += 'x';
+  if (maxLength >= 0 && value.length > maxLength) value = value.slice(0, maxLength);
+  if (!value && minLength > 0) value = 'x'.repeat(minLength);
+  return value;
+}
+
+function stringCandidates(schema: SchemaRecord): string[] {
+  const candidates: string[] = [];
+  if (typeof schema.default === 'string') candidates.push(schema.default);
+  if (typeof schema.description === 'string') candidates.push(schema.description);
+  candidates.push('sample', 'ok', 'done', 'pass', 'fail');
+  return candidates;
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function sampleNumber(
+  schema: SchemaRecord,
+  rng: RandomNumberGenerator,
+  asInteger: boolean
+): number {
+  const minimum = finiteNumber(schema.minimum, 0);
+  const maximum = finiteNumber(schema.maximum, 10);
+  if (maximum < minimum) {
+    return asInteger ? Math.round(minimum) : minimum;
+  }
+  if (asInteger) {
+    return randomInt(rng, Math.ceil(minimum), Math.floor(maximum));
+  }
+  return minimum + (maximum - minimum) * rng();
+}
+
+function sampleArray(schema: SchemaRecord, rng: RandomNumberGenerator, depth: number): unknown[] {
+  const minItems = Number.isInteger(schema.minItems) ? Number(schema.minItems) : 0;
+  const rawMaximum = Number.isInteger(schema.maxItems) ? Number(schema.maxItems) : minItems + 2;
+  const maxItems = Math.max(minItems, Math.min(rawMaximum, 3));
+  const length = randomInt(rng, minItems, maxItems);
+  const itemsSchema = Array.isArray(schema.items)
+    ? randomPick<unknown>(rng, schema.items, {})
+    : schema.items || {};
+  const values: unknown[] = [];
+  for (let index = 0; index < length; index += 1) {
+    values.push(sampleFromSchema(itemsSchema, rng, depth + 1));
+  }
+  return values;
+}
+
+function sampleObject(
+  schema: SchemaRecord,
+  rng: RandomNumberGenerator,
+  depth: number
+): Record<string, unknown> {
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const value: Record<string, unknown> = {};
+  for (const [key, propertySchema] of Object.entries(properties)) {
+    value[key] = sampleFromSchema(propertySchema, rng, depth + 1);
+  }
+  return value;
+}
+
+type SampleBranch = { matched: true; value: unknown } | { matched: false };
+
+function isNonEmptyArray(value: unknown): value is unknown[] {
+  return Array.isArray(value) && value.length > 0;
+}
+
+function sampleSchemaKeyword(
+  schema: SchemaRecord,
+  rng: RandomNumberGenerator,
+  depth: number
+): SampleBranch {
+  if (schema.const !== undefined) return { matched: true, value: schema.const };
+  if (isNonEmptyArray(schema.enum)) {
+    return { matched: true, value: randomPick<unknown>(rng, schema.enum, null) };
+  }
+  if (isNonEmptyArray(schema.oneOf)) {
+    const selected = randomPick<unknown>(rng, schema.oneOf, null);
+    return { matched: true, value: sampleFromSchema(selected, rng, depth + 1) };
+  }
+  if (isNonEmptyArray(schema.anyOf)) {
+    const selected = randomPick<unknown>(rng, schema.anyOf, null);
+    return { matched: true, value: sampleFromSchema(selected, rng, depth + 1) };
+  }
+  if (isNonEmptyArray(schema.allOf)) {
+    return { matched: true, value: sampleFromSchema(schema.allOf[0], rng, depth + 1) };
+  }
+  return { matched: false };
+}
+
+function sampleSchemaType(
+  schema: SchemaRecord,
+  rng: RandomNumberGenerator,
+  depth: number
+): SampleBranch {
+  const type = normalizeType(schema);
+  if (type === 'boolean') return { matched: true, value: rng() >= 0.5 };
+  if (type === 'integer') return { matched: true, value: sampleNumber(schema, rng, true) };
+  if (type === 'number') return { matched: true, value: sampleNumber(schema, rng, false) };
+  if (type === 'array') return { matched: true, value: sampleArray(schema, rng, depth) };
+  if (type === 'object' || schema.properties) {
+    return { matched: true, value: sampleObject(schema, rng, depth) };
+  }
+  return { matched: false };
+}
+
+export function sampleFromSchema(
+  schemaValue: unknown,
+  rng: RandomNumberGenerator,
+  depth = 0
+): unknown {
+  if (!isRecord(schemaValue) || depth > 4) {
+    return null;
+  }
+  const keyword = sampleSchemaKeyword(schemaValue, rng, depth);
+  if (keyword.matched) return keyword.value;
+  const typed = sampleSchemaType(schemaValue, rng, depth);
+  if (typed.matched) return typed.value;
+  return sampleString(schemaValue, rng);
+}
+
+export function sampleResultData(
+  agentConfig: RandomAgentConfig,
+  rng: RandomNumberGenerator
+): unknown {
+  const schema = agentConfig.jsonSchema || agentConfig.structuredOutput || null;
+  if (schema) {
+    return sampleFromSchema(schema, rng);
+  }
+  return { summary: 'sample', result: 'sample' };
+}

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

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneAgentConfigs = cloneAgentConfigs;
+exports.addAgentsToState = addAgentsToState;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isRandomAgentConfig(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        (value.role === undefined || typeof value.role === 'string'));
+}
+function cloneAgentConfigs(agents) {
+    const cloned = JSON.parse(JSON.stringify(agents));
+    return Array.isArray(cloned) ? cloned.filter(isRandomAgentConfig) : [];
+}
+function addAgentsToState(state, agents) {
+    if (!Array.isArray(agents))
+        return;
+    for (const agent of agents) {
+        if (!isRandomAgentConfig(agent))
+            continue;
+        if (state.agentConfigs.some((existing) => existing.id === agent.id))
+            continue;
+        state.agentConfigs.push(agent);
+        state.cluster.agents.push({ id: agent.id, role: agent.role });
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { RandomAgentConfig, RandomSimulationState } from './random-topology-contracts';
+
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isRandomAgentConfig(value: unknown): value is RandomAgentConfig {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    (value.role === undefined || typeof value.role === 'string')
+  );
+}
+
+export function cloneAgentConfigs(agents: RandomAgentConfig[]): RandomAgentConfig[] {
+  const cloned: unknown = JSON.parse(JSON.stringify(agents));
+  return Array.isArray(cloned) ? cloned.filter(isRandomAgentConfig) : [];
+}
+
+export function addAgentsToState(state: RandomSimulationState, agents: unknown): void {
+  if (!Array.isArray(agents)) return;
+  for (const agent of agents) {
+    if (!isRandomAgentConfig(agent)) continue;
+    if (state.agentConfigs.some((existing) => existing.id === agent.id)) continue;
+    state.agentConfigs.push(agent);
+    state.cluster.agents.push({ id: agent.id, role: agent.role });
+  }
+}

package/src/template-validation/random-topology-trigger-evaluation.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishTerminal = publishTerminal;
+exports.evaluateAgentTrigger = evaluateAgentTrigger;
+const randomTopologyRuntime = require("./random-topology-runtime");
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function publishTerminal(options) {
+    const { context, agentConfig, topic, text, data } = options;
+    context.messageBus.publish({
+        cluster_id: context.state.cluster.id,
+        topic,
+        sender: agentConfig.id,
+        receiver: 'system',
+        content: { text, data },
+    });
+}
+function evaluateAgentTrigger(context, agentConfig, trigger, message) {
+    try {
+        return {
+            kind: 'match',
+            matches: randomTopologyRuntime.evaluateTrigger({
+                trigger,
+                message,
+                agent: {
+                    id: agentConfig.id,
+                    role: agentConfig.role,
+                    iteration: context.iterations.get(agentConfig.id) || 0,
+                    cluster_id: context.state.cluster.id,
+                },
+                logicEngine: context.logicEngine,
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            kind: 'outcome',
+            outcome: {
+                ok: false,
+                reason: `trigger logic error (${agentConfig.id} on ${message.topic}): ${errorMessage(error)}`,
+            },
+        };
+    }
+}

package/src/template-validation/random-topology-trigger-evaluation.ts

@@ -0,0 +1,65 @@
+import type {
+  RandomAgentConfig,
+  RandomDispatchContext,
+  RandomTrigger,
+  ScenarioOutcome,
+  SimulationMessage,
+} from './random-topology-contracts';
+import randomTopologyRuntime = require('./random-topology-runtime');
+
+export type TriggerEvaluation =
+  | { kind: 'match'; matches: boolean }
+  | { kind: 'outcome'; outcome: ScenarioOutcome };
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function publishTerminal(options: {
+  context: RandomDispatchContext;
+  agentConfig: RandomAgentConfig;
+  topic: 'CLUSTER_COMPLETE' | 'CLUSTER_FAILED';
+  text: string;
+  data: Record<string, unknown>;
+}): void {
+  const { context, agentConfig, topic, text, data } = options;
+  context.messageBus.publish({
+    cluster_id: context.state.cluster.id,
+    topic,
+    sender: agentConfig.id,
+    receiver: 'system',
+    content: { text, data },
+  });
+}
+
+export function evaluateAgentTrigger(
+  context: RandomDispatchContext,
+  agentConfig: RandomAgentConfig,
+  trigger: RandomTrigger,
+  message: SimulationMessage
+): TriggerEvaluation {
+  try {
+    return {
+      kind: 'match',
+      matches: randomTopologyRuntime.evaluateTrigger({
+        trigger,
+        message,
+        agent: {
+          id: agentConfig.id,
+          role: agentConfig.role,
+          iteration: context.iterations.get(agentConfig.id) || 0,
+          cluster_id: context.state.cluster.id,
+        },
+        logicEngine: context.logicEngine,
+      }),
+    };
+  } catch (error) {
+    return {
+      kind: 'outcome',
+      outcome: {
+        ok: false,
+        reason: `trigger logic error (${agentConfig.id} on ${message.topic}): ${errorMessage(error)}`,
+      },
+    };
+  }
+}

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

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAgentTrigger = executeAgentTrigger;
+const simulationAgentRuntime = require("./simulation-agent-runtime");
+const simulation_agent_1 = require("./simulation-agent");
+const random_topology_trigger_evaluation_1 = require("./random-topology-trigger-evaluation");
+const random_topology_schema_1 = require("./random-topology-schema");
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function executeAgentTrigger(context, agentConfig, trigger, message) {
+    const evaluation = (0, random_topology_trigger_evaluation_1.evaluateAgentTrigger)(context, agentConfig, trigger, message);
+    if (evaluation.kind === 'outcome')
+        return evaluation.outcome;
+    if (!evaluation.matches)
+        return null;
+    const action = trigger.action || 'execute_task';
+    if (action === 'stop_cluster') {
+        (0, random_topology_trigger_evaluation_1.publishTerminal)({
+            context,
+            agentConfig,
+            topic: 'CLUSTER_COMPLETE',
+            text: 'simulated completion',
+            data: { topic: message.topic },
+        });
+        return null;
+    }
+    if (action !== 'execute_task')
+        return null;
+    const nextIteration = (context.iterations.get(agentConfig.id) || 0) + 1;
+    context.iterations.set(agentConfig.id, nextIteration);
+    const maxIterations = maximumIterations(agentConfig);
+    if (nextIteration > maxIterations) {
+        (0, random_topology_trigger_evaluation_1.publishTerminal)({
+            context,
+            agentConfig,
+            topic: 'CLUSTER_FAILED',
+            text: `maxIterations exceeded: ${agentConfig.id}`,
+            data: { maxIterations, iteration: nextIteration },
+        });
+        return null;
+    }
+    const sampledResult = (0, random_topology_schema_1.sampleResultData)(agentConfig, context.rng);
+    const simulationAgent = (0, simulation_agent_1.createSimulationAgent)({
+        agentConfig,
+        cluster: context.state.cluster,
+        messageBus: context.messageBus,
+        iteration: nextIteration,
+        currentTaskId: `sim-${agentConfig.id}-${nextIteration}`,
+    });
+    try {
+        await simulationAgentRuntime.executeHook({
+            hook: agentConfig.hooks?.onComplete,
+            agent: simulationAgent,
+            message,
+            result: {
+                output: JSON.stringify(sampledResult || {}),
+                success: true,
+                taskId: `sim-task-${agentConfig.id}-${nextIteration}`,
+            },
+            messageBus: context.messageBus,
+            cluster: context.state.cluster,
+        });
+        return null;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `hook execution failed (${agentConfig.id}): ${errorMessage(error)}`,
+        };
+    }
+}
+function maximumIterations(agentConfig) {
+    return Number.isInteger(agentConfig.maxIterations) ? Number(agentConfig.maxIterations) : 100;
+}

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

@@ -0,0 +1,88 @@
+import simulationAgentRuntime = require('./simulation-agent-runtime');
+import { createSimulationAgent } from './simulation-agent';
+import type {
+  RandomAgentConfig,
+  RandomDispatchContext,
+  RandomTrigger,
+  ScenarioOutcome,
+  SimulationMessage,
+} from './random-topology-contracts';
+import { evaluateAgentTrigger, publishTerminal } from './random-topology-trigger-evaluation';
+import { sampleResultData } from './random-topology-schema';
+
+type TriggerOutcome = ScenarioOutcome | null;
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function executeAgentTrigger(
+  context: RandomDispatchContext,
+  agentConfig: RandomAgentConfig,
+  trigger: RandomTrigger,
+  message: SimulationMessage
+): Promise<TriggerOutcome> {
+  const evaluation = evaluateAgentTrigger(context, agentConfig, trigger, message);
+  if (evaluation.kind === 'outcome') return evaluation.outcome;
+  if (!evaluation.matches) return null;
+
+  const action = trigger.action || 'execute_task';
+  if (action === 'stop_cluster') {
+    publishTerminal({
+      context,
+      agentConfig,
+      topic: 'CLUSTER_COMPLETE',
+      text: 'simulated completion',
+      data: { topic: message.topic },
+    });
+    return null;
+  }
+  if (action !== 'execute_task') return null;
+
+  const nextIteration = (context.iterations.get(agentConfig.id) || 0) + 1;
+  context.iterations.set(agentConfig.id, nextIteration);
+  const maxIterations = maximumIterations(agentConfig);
+  if (nextIteration > maxIterations) {
+    publishTerminal({
+      context,
+      agentConfig,
+      topic: 'CLUSTER_FAILED',
+      text: `maxIterations exceeded: ${agentConfig.id}`,
+      data: { maxIterations, iteration: nextIteration },
+    });
+    return null;
+  }
+
+  const sampledResult = sampleResultData(agentConfig, context.rng);
+  const simulationAgent = createSimulationAgent({
+    agentConfig,
+    cluster: context.state.cluster,
+    messageBus: context.messageBus,
+    iteration: nextIteration,
+    currentTaskId: `sim-${agentConfig.id}-${nextIteration}`,
+  });
+  try {
+    await simulationAgentRuntime.executeHook({
+      hook: agentConfig.hooks?.onComplete,
+      agent: simulationAgent,
+      message,
+      result: {
+        output: JSON.stringify(sampledResult || {}),
+        success: true,
+        taskId: `sim-task-${agentConfig.id}-${nextIteration}`,
+      },
+      messageBus: context.messageBus,
+      cluster: context.state.cluster,
+    });
+    return null;
+  } catch (error) {
+    return {
+      ok: false,
+      reason: `hook execution failed (${agentConfig.id}): ${errorMessage(error)}`,
+    };
+  }
+}
+
+function maximumIterations(agentConfig: RandomAgentConfig): number {
+  return Number.isInteger(agentConfig.maxIterations) ? Number(agentConfig.maxIterations) : 100;
+}