@the-open-engine/zeroshot 6.38.1 → 6.39.0

package/src/agent/agent-liveness-poll.ts

@@ -0,0 +1,163 @@
+interface AgentStuckDetectorModule {
+  isPlatformSupported(): boolean;
+}
+
+interface LivenessIsolation {
+  enabled?: boolean;
+}
+
+interface NestedExecutions {
+  hasActive?: boolean;
+}
+
+interface LivenessAgent {
+  currentTask?: unknown;
+  currentTaskId?: unknown;
+  isolation?: LivenessIsolation | null;
+  nestedExecutions?: NestedExecutions | null;
+  livenessTerminationStarted?: boolean;
+  livenessTerminationContext?: unknown;
+  livenessTerminationRetryAt: number;
+  taskStartedAt?: number | null;
+  lastOutputTime?: number | null;
+  consecutiveStaleWarnings: number;
+  _publishLifecycle(event: string, details: Record<string, unknown>): unknown;
+}
+
+interface TaskTiming {
+  taskRuntime: number;
+  timeSinceLastOutput: number;
+  lastOutputTime: number;
+}
+
+type AttemptTermination = (agent: LivenessAgent, settings: unknown) => unknown;
+
+type BeginTermination = (
+  agent: LivenessAgent,
+  settings: unknown,
+  reason: string,
+  code: string,
+  eventData: Record<string, unknown>
+) => unknown;
+
+interface LivenessPollContext {
+  agent: LivenessAgent;
+  settings: unknown;
+  configuredTimeout: number | null;
+  staleDuration: number;
+  warningsBeforeKill: number;
+  attemptTermination: AttemptTermination;
+  beginTermination: BeginTermination;
+}
+
+function isAgentStuckDetectorModule(value: unknown): value is AgentStuckDetectorModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'isPlatformSupported' in value &&
+    typeof value.isPlatformSupported === 'function'
+  );
+}
+
+const agentStuckDetectorModule: unknown = require('./agent-stuck-detector');
+if (!isAgentStuckDetectorModule(agentStuckDetectorModule)) {
+  throw new TypeError('agent-stuck-detector must export isPlatformSupported');
+}
+const isPlatformSupported = agentStuckDetectorModule.isPlatformSupported;
+
+function hasRecoverableTask(agent: LivenessAgent): boolean {
+  return (
+    Boolean(agent.currentTask) ||
+    Boolean(agent.isolation?.enabled && agent.currentTaskId) ||
+    agent.nestedExecutions?.hasActive === true
+  );
+}
+
+function handlePendingTermination(
+  agent: LivenessAgent,
+  settings: unknown,
+  now: number,
+  attemptTermination: AttemptTermination
+): boolean {
+  if (!agent.livenessTerminationContext) return false;
+  if (now >= agent.livenessTerminationRetryAt) attemptTermination(agent, settings);
+  return true;
+}
+
+function taskTiming(agent: LivenessAgent, now: number): TaskTiming {
+  const taskStartedAt = agent.taskStartedAt || agent.lastOutputTime || now;
+  const lastOutputTime = agent.lastOutputTime || taskStartedAt;
+  return {
+    taskRuntime: now - taskStartedAt,
+    timeSinceLastOutput: now - lastOutputTime,
+    lastOutputTime,
+  };
+}
+
+function handleTaskTimeout(context: LivenessPollContext, timing: TaskTiming): boolean {
+  const { agent, settings, configuredTimeout, beginTermination } = context;
+  if (!configuredTimeout || timing.taskRuntime < configuredTimeout) return false;
+  beginTermination(
+    agent,
+    settings,
+    `Task timed out after ${configuredTimeout}ms`,
+    'AGENT_TASK_TIMEOUT',
+    {
+      taskId: agent.currentTaskId,
+      taskRuntime: timing.taskRuntime,
+      timeout: configuredTimeout,
+    }
+  );
+  return true;
+}
+
+function publishStaleWarning(context: LivenessPollContext, timing: TaskTiming): void {
+  const { agent, staleDuration, warningsBeforeKill } = context;
+  agent.consecutiveStaleWarnings += 1;
+  agent._publishLifecycle('AGENT_STALE_WARNING', {
+    taskId: agent.currentTaskId,
+    timeSinceLastOutput: timing.timeSinceLastOutput,
+    staleDuration,
+    lastOutputTime: timing.lastOutputTime,
+    consecutiveWarnings: agent.consecutiveStaleWarnings,
+    warningsBeforeKill,
+    processDiagnosticsAvailable: isPlatformSupported(),
+    analysis: `Provider produced no output for ${timing.timeSinceLastOutput}ms`,
+  });
+}
+
+function terminateForInactivity(context: LivenessPollContext, timing: TaskTiming): void {
+  const { agent, settings, staleDuration, beginTermination } = context;
+  beginTermination(
+    agent,
+    settings,
+    `Provider produced no output for ${timing.timeSinceLastOutput}ms`,
+    'PROVIDER_INACTIVITY_TIMEOUT',
+    {
+      taskId: agent.currentTaskId,
+      timeSinceLastOutput: timing.timeSinceLastOutput,
+      staleDuration,
+      consecutiveWarnings: agent.consecutiveStaleWarnings,
+    }
+  );
+}
+
+function createLivenessPoll(context: LivenessPollContext): () => void {
+  const { agent, settings, staleDuration, warningsBeforeKill, attemptTermination } = context;
+  return () => {
+    if (!hasRecoverableTask(agent) || agent.livenessTerminationStarted) return;
+    const now = Date.now();
+    if (handlePendingTermination(agent, settings, now, attemptTermination)) return;
+    const timing = taskTiming(agent, now);
+    if (handleTaskTimeout(context, timing)) return;
+    if (timing.timeSinceLastOutput < staleDuration) {
+      agent.consecutiveStaleWarnings = 0;
+      return;
+    }
+    publishStaleWarning(context, timing);
+    if (agent.consecutiveStaleWarnings < warningsBeforeKill) return;
+    terminateForInactivity(context, timing);
+  };
+}
+
+export = { createLivenessPoll };

package/src/agent/agent-quality-gate-schema.js

@@ -1,102 +1,93 @@
+"use strict";
 function buildQualityGateSchema() {
-  return {
-    type: 'array',
-    description: 'Tool-neutral ship handoff quality gate evidence for configured required gates.',
-    items: {
-      type: 'object',
-      properties: {
-        id: {
-          type: 'string',
-          description: 'Stable gate id matching the configured required quality gate.',
-        },
-        name: {
-          type: 'string',
-          description: 'Optional display name for the gate.',
-        },
-        status: {
-          type: 'string',
-          enum: ['PASS', 'FAIL', 'UNAVAILABLE'],
-          description: 'PASS only when the gate completed successfully.',
-        },
-        scope: {
-          type: 'string',
-          description: 'Optional repo-defined scope for the gate.',
-        },
-        evidence: {
-          type: 'object',
-          properties: {
-            command: { type: 'string' },
-            exitCode: { type: 'integer' },
-            output: { type: 'string' },
-            proof: {
-              type: 'object',
-              description: 'Optional command proof metadata when the gate used cmdproof.',
-              properties: {
-                profile: { type: 'string' },
-                reused: { type: 'boolean' },
-                status: { type: 'string' },
-              },
+    return {
+        type: 'array',
+        description: 'Tool-neutral ship handoff quality gate evidence for configured required gates.',
+        items: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Stable gate id matching the configured required quality gate.',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Optional display name for the gate.',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['PASS', 'FAIL', 'UNAVAILABLE'],
+                    description: 'PASS only when the gate completed successfully.',
+                },
+                scope: {
+                    type: 'string',
+                    description: 'Optional repo-defined scope for the gate.',
+                },
+                evidence: {
+                    type: 'object',
+                    properties: {
+                        command: { type: 'string' },
+                        exitCode: { type: 'integer' },
+                        output: { type: 'string' },
+                        proof: {
+                            type: 'object',
+                            description: 'Optional command proof metadata when the gate used cmdproof.',
+                            properties: {
+                                profile: { type: 'string' },
+                                reused: { type: 'boolean' },
+                                status: { type: 'string' },
+                            },
+                        },
+                    },
+                    required: ['command', 'exitCode', 'output'],
+                },
+                completedAt: {
+                    anyOf: [{ type: 'string' }, { type: 'number' }],
+                    description: 'When the gate completed, as an ISO string or numeric timestamp.',
+                },
+                timestamp: {
+                    anyOf: [{ type: 'string' }, { type: 'number' }],
+                    description: 'Alternate completion timestamp, as an ISO string or numeric timestamp.',
+                },
+                stale: {
+                    type: 'boolean',
+                    description: 'True when this evidence is known stale and must block handoff.',
+                },
+                reason: { type: 'string' },
             },
-          },
-          required: ['command', 'exitCode', 'output'],
-        },
-        completedAt: {
-          anyOf: [{ type: 'string' }, { type: 'number' }],
-          description: 'When the gate completed, as an ISO string or numeric timestamp.',
-        },
-        timestamp: {
-          anyOf: [{ type: 'string' }, { type: 'number' }],
-          description: 'Alternate completion timestamp, as an ISO string or numeric timestamp.',
-        },
-        stale: {
-          type: 'boolean',
-          description: 'True when this evidence is known stale and must block handoff.',
+            required: ['id', 'status', 'evidence'],
         },
-        reason: { type: 'string' },
-      },
-      required: ['id', 'status', 'evidence'],
-    },
-  };
+    };
 }
-
 function hasRequiredQualityGates(config) {
-  return Array.isArray(config.requiredQualityGates) && config.requiredQualityGates.length > 0;
+    return Array.isArray(config.requiredQualityGates) && config.requiredQualityGates.length > 0;
 }
-
 function shouldApplyValidatorQualityGateDefaults(config) {
-  return (
-    config.role === 'validator' && config.outputFormat === 'json' && hasRequiredQualityGates(config)
-  );
+    return (config.role === 'validator' && config.outputFormat === 'json' && hasRequiredQualityGates(config));
 }
-
 function applyValidatorQualityGateSchema(config) {
-  if (!shouldApplyValidatorQualityGateDefaults(config)) {
-    return;
-  }
-
-  const properties = config.jsonSchema?.properties;
-  if (properties && !properties.qualityGates) {
-    properties.qualityGates = buildQualityGateSchema();
-  }
+    if (!shouldApplyValidatorQualityGateDefaults(config)) {
+        return;
+    }
+    const properties = config.jsonSchema?.properties;
+    if (properties && !properties.qualityGates) {
+        properties.qualityGates = buildQualityGateSchema();
+    }
 }
-
 function applyValidatorQualityGatePublishMapping(config) {
-  if (!shouldApplyValidatorQualityGateDefaults(config)) {
-    return;
-  }
-
-  const data = config.hooks?.onComplete?.config?.content?.data;
-  if (data && data.qualityGates === undefined) {
-    data.qualityGates = '{{result.qualityGates}}';
-  }
+    if (!shouldApplyValidatorQualityGateDefaults(config)) {
+        return;
+    }
+    const data = config.hooks?.onComplete?.config?.content?.data;
+    if (data && data.qualityGates === undefined) {
+        data.qualityGates = '{{result.qualityGates}}';
+    }
 }
-
 function applyValidatorQualityGateDefaults(config) {
-  applyValidatorQualityGateSchema(config);
-  applyValidatorQualityGatePublishMapping(config);
+    applyValidatorQualityGateSchema(config);
+    applyValidatorQualityGatePublishMapping(config);
 }
-
 module.exports = {
-  applyValidatorQualityGateDefaults,
-  buildQualityGateSchema,
+    applyValidatorQualityGateDefaults,
+    buildQualityGateSchema,
 };

package/src/agent/agent-quality-gate-schema.ts

@@ -0,0 +1,135 @@
+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 QualityGatePublishData {
+  qualityGates?: unknown;
+  [key: string]: unknown;
+}
+
+interface AgentQualityGateConfig {
+  role?: string;
+  outputFormat?: string;
+  requiredQualityGates?: unknown;
+  jsonSchema?: JsonSchema;
+  hooks?: {
+    onComplete?: {
+      config?: {
+        content?: {
+          data?: QualityGatePublishData;
+        };
+      };
+    };
+  };
+}
+
+function buildQualityGateSchema(): JsonSchema {
+  return {
+    type: 'array',
+    description: 'Tool-neutral ship handoff quality gate evidence for configured required gates.',
+    items: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Stable gate id matching the configured required quality gate.',
+        },
+        name: {
+          type: 'string',
+          description: 'Optional display name for the gate.',
+        },
+        status: {
+          type: 'string',
+          enum: ['PASS', 'FAIL', 'UNAVAILABLE'],
+          description: 'PASS only when the gate completed successfully.',
+        },
+        scope: {
+          type: 'string',
+          description: 'Optional repo-defined scope for the gate.',
+        },
+        evidence: {
+          type: 'object',
+          properties: {
+            command: { type: 'string' },
+            exitCode: { type: 'integer' },
+            output: { type: 'string' },
+            proof: {
+              type: 'object',
+              description: 'Optional command proof metadata when the gate used cmdproof.',
+              properties: {
+                profile: { type: 'string' },
+                reused: { type: 'boolean' },
+                status: { type: 'string' },
+              },
+            },
+          },
+          required: ['command', 'exitCode', 'output'],
+        },
+        completedAt: {
+          anyOf: [{ type: 'string' }, { type: 'number' }],
+          description: 'When the gate completed, as an ISO string or numeric timestamp.',
+        },
+        timestamp: {
+          anyOf: [{ type: 'string' }, { type: 'number' }],
+          description: 'Alternate completion timestamp, as an ISO string or numeric timestamp.',
+        },
+        stale: {
+          type: 'boolean',
+          description: 'True when this evidence is known stale and must block handoff.',
+        },
+        reason: { type: 'string' },
+      },
+      required: ['id', 'status', 'evidence'],
+    },
+  };
+}
+
+function hasRequiredQualityGates(config: AgentQualityGateConfig): boolean {
+  return Array.isArray(config.requiredQualityGates) && config.requiredQualityGates.length > 0;
+}
+
+function shouldApplyValidatorQualityGateDefaults(config: AgentQualityGateConfig): boolean {
+  return (
+    config.role === 'validator' && config.outputFormat === 'json' && hasRequiredQualityGates(config)
+  );
+}
+
+function applyValidatorQualityGateSchema(config: AgentQualityGateConfig): void {
+  if (!shouldApplyValidatorQualityGateDefaults(config)) {
+    return;
+  }
+
+  const properties = config.jsonSchema?.properties;
+  if (properties && !properties.qualityGates) {
+    properties.qualityGates = buildQualityGateSchema();
+  }
+}
+
+function applyValidatorQualityGatePublishMapping(config: AgentQualityGateConfig): void {
+  if (!shouldApplyValidatorQualityGateDefaults(config)) {
+    return;
+  }
+
+  const data = config.hooks?.onComplete?.config?.content?.data;
+  if (data && data.qualityGates === undefined) {
+    data.qualityGates = '{{result.qualityGates}}';
+  }
+}
+
+function applyValidatorQualityGateDefaults(config: AgentQualityGateConfig): void {
+  applyValidatorQualityGateSchema(config);
+  applyValidatorQualityGatePublishMapping(config);
+}
+
+export = {
+  applyValidatorQualityGateDefaults,
+  buildQualityGateSchema,
+};

package/src/agent/agent-quality-gates-context.js

@@ -1,56 +1,50 @@
-const { normalizeRequiredQualityGates } = require('../quality-gates');
-
+"use strict";
+function isQualityGatesModule(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'normalizeRequiredQualityGates' in value &&
+        typeof value.normalizeRequiredQualityGates === 'function');
+}
+const qualityGatesModule = require('../quality-gates');
+if (!isQualityGatesModule(qualityGatesModule)) {
+    throw new TypeError('quality-gates must export normalizeRequiredQualityGates');
+}
+const normalizeRequiredQualityGates = qualityGatesModule.normalizeRequiredQualityGates;
 function appendGateDetails(lines, gate, index) {
-  lines.push(`${index + 1}. id: ${gate.id}${gate.scope ? `, scope: ${gate.scope}` : ''}`);
-  if (gate.description) {
-    lines.push(`   description: ${gate.description}`);
-  }
-  if (gate.command) {
-    lines.push(`   command: ${gate.command}`);
-  }
-  if (gate.profile || gate.proofProfile) {
-    lines.push(`   cmdproof profile: ${gate.profile || gate.proofProfile}`);
-    lines.push(`   cmdproof helper: zeroshot cmdproof check ${gate.id}`);
-  }
+    lines.push(`${index + 1}. id: ${gate.id}${gate.scope ? `, scope: ${gate.scope}` : ''}`);
+    if (gate.description) {
+        lines.push(`   description: ${gate.description}`);
+    }
+    if (gate.command) {
+        lines.push(`   command: ${gate.command}`);
+    }
+    if (gate.profile || gate.proofProfile) {
+        lines.push(`   cmdproof profile: ${gate.profile || gate.proofProfile}`);
+        lines.push(`   cmdproof helper: zeroshot cmdproof check ${gate.id}`);
+    }
 }
-
 function buildRequiredQualityGatesSection(config) {
-  if (config.role !== 'validator') {
-    return '';
-  }
-
-  const gates = normalizeRequiredQualityGates(config.requiredQualityGates);
-  if (gates.length === 0) {
-    return '';
-  }
-
-  const lines = [
-    '## Required Handoff Quality Gates',
-    '',
-    'Before approving implementation handoff, publish one `qualityGates` entry for each configured required gate.',
-    'Each entry must use the configured `id` and `scope` when a scope is configured.',
-    '',
-    'Configured gates:',
-  ];
-
-  gates.forEach((gate, index) => appendGateDetails(lines, gate, index));
-
-  lines.push(
-    '',
-    'For each configured gate:',
-    '- Run the configured command when one is provided by repo or cluster config.',
-    '- For gates with a cmdproof profile, run `zeroshot cmdproof check <id>` before considering a raw command.',
-    '- Put the command, numeric exit code, and string output in `evidence`.',
-    '- Set `status` to `PASS` only when the gate completes successfully.',
-    '- If a required gate fails, set `approved` to false and publish status `FAIL`.',
-    '- If a required gate cannot run because its command, tool, or service is unavailable, set `approved` to false and publish status `UNAVAILABLE`.',
-    '- Use `completedAt` or `timestamp` from the current validation run; stale evidence must be marked with `stale: true`.',
-    ''
-  );
-
-  return lines.join('\n');
+    if (config.role !== 'validator') {
+        return '';
+    }
+    const gates = normalizeRequiredQualityGates(config.requiredQualityGates);
+    if (gates.length === 0) {
+        return '';
+    }
+    const lines = [
+        '## Required Handoff Quality Gates',
+        '',
+        'Before approving implementation handoff, publish one `qualityGates` entry for each configured required gate.',
+        'Each entry must use the configured `id` and `scope` when a scope is configured.',
+        '',
+        'Configured gates:',
+    ];
+    gates.forEach((gate, index) => appendGateDetails(lines, gate, index));
+    lines.push('', 'For each configured gate:', '- Run the configured command when one is provided by repo or cluster config.', '- For gates with a cmdproof profile, run `zeroshot cmdproof check <id>` before considering a raw command.', '- Put the command, numeric exit code, and string output in `evidence`.', '- Set `status` to `PASS` only when the gate completes successfully.', '- If a required gate fails, set `approved` to false and publish status `FAIL`.', '- If a required gate cannot run because its command, tool, or service is unavailable, ' +
+        'set `approved` to false and publish status `UNAVAILABLE`.', '- Use `completedAt` or `timestamp` from the current validation run; ' +
+        'stale evidence must be marked with `stale: true`.', '');
+    return lines.join('\n');
 }
-
 module.exports = {
-  buildRequiredQualityGatesSection,
+    buildRequiredQualityGatesSection,
 };

package/src/agent/agent-quality-gates-context.ts

@@ -0,0 +1,91 @@
+type StringList = string[];
+
+interface RequiredQualityGate {
+  id: string;
+  scope?: string;
+  description?: string;
+  command?: string;
+  profile?: string;
+  proofProfile?: string;
+}
+
+interface AgentQualityGateConfig {
+  role?: string;
+  requiredQualityGates?: unknown;
+}
+
+interface QualityGatesModule {
+  normalizeRequiredQualityGates(value: unknown): RequiredQualityGate[];
+}
+
+function isQualityGatesModule(value: unknown): value is QualityGatesModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'normalizeRequiredQualityGates' in value &&
+    typeof value.normalizeRequiredQualityGates === 'function'
+  );
+}
+
+const qualityGatesModule: unknown = require('../quality-gates');
+if (!isQualityGatesModule(qualityGatesModule)) {
+  throw new TypeError('quality-gates must export normalizeRequiredQualityGates');
+}
+const normalizeRequiredQualityGates = qualityGatesModule.normalizeRequiredQualityGates;
+
+function appendGateDetails(lines: StringList, gate: RequiredQualityGate, index: number): void {
+  lines.push(`${index + 1}. id: ${gate.id}${gate.scope ? `, scope: ${gate.scope}` : ''}`);
+  if (gate.description) {
+    lines.push(`   description: ${gate.description}`);
+  }
+  if (gate.command) {
+    lines.push(`   command: ${gate.command}`);
+  }
+  if (gate.profile || gate.proofProfile) {
+    lines.push(`   cmdproof profile: ${gate.profile || gate.proofProfile}`);
+    lines.push(`   cmdproof helper: zeroshot cmdproof check ${gate.id}`);
+  }
+}
+
+function buildRequiredQualityGatesSection(config: AgentQualityGateConfig): string {
+  if (config.role !== 'validator') {
+    return '';
+  }
+
+  const gates = normalizeRequiredQualityGates(config.requiredQualityGates);
+  if (gates.length === 0) {
+    return '';
+  }
+
+  const lines = [
+    '## Required Handoff Quality Gates',
+    '',
+    'Before approving implementation handoff, publish one `qualityGates` entry for each configured required gate.',
+    'Each entry must use the configured `id` and `scope` when a scope is configured.',
+    '',
+    'Configured gates:',
+  ];
+
+  gates.forEach((gate, index) => appendGateDetails(lines, gate, index));
+
+  lines.push(
+    '',
+    'For each configured gate:',
+    '- Run the configured command when one is provided by repo or cluster config.',
+    '- For gates with a cmdproof profile, run `zeroshot cmdproof check <id>` before considering a raw command.',
+    '- Put the command, numeric exit code, and string output in `evidence`.',
+    '- Set `status` to `PASS` only when the gate completes successfully.',
+    '- If a required gate fails, set `approved` to false and publish status `FAIL`.',
+    '- If a required gate cannot run because its command, tool, or service is unavailable, ' +
+      'set `approved` to false and publish status `UNAVAILABLE`.',
+    '- Use `completedAt` or `timestamp` from the current validation run; ' +
+      'stale evidence must be marked with `stale: true`.',
+    ''
+  );
+
+  return lines.join('\n');
+}
+
+export = {
+  buildRequiredQualityGatesSection,
+};