refactor: migrate agent schema and liveness utilities to TypeScript (#996)

## Summary

- migrate quality-gate schema construction and schema normalization
utilities from JavaScript to strict TypeScript
- migrate context metrics and liveness polling with explicit runtime
boundary types
- preserve CommonJS entrypoints and verify compiled outputs remain in
the npm package

## Validation

- `npm run prepack`
- `npm test` (2,901 passing; 18 pending)
- `npm run typecheck`
- targeted ESLint and Prettier checks
- direct old/new behavior and export parity for every migrated module
- liveness parity across 10 state-machine scenarios
- `npx mocha tests/agent-stuck-recovery.test.js
tests/isolated-task-recovery.test.js` (26 passing)
- Opcore hypothetical, changed, Sense, graph update, introduced-change,
and staged gates
- npm package dry-run smoke (all four compiled runtime outputs present)

Author: tomdps

.gitignore

@@ -173,8 +173,12 @@ src/omp-session-limits.js
 src/agent/agent-trigger-evaluator.js
 src/agent/agent-command-proofs-context.js
 src/agent/agent-quality-gates-context.js
+src/agent/agent-quality-gate-schema.js
 src/agent/rate-limit-backoff.js
 src/agent/guidance-queue.js
+src/agent/schema-utils.js
+src/agent/context-metrics.js
+src/agent/agent-liveness-poll.js
 src/agent/context-replay-policy.js
 src/agent/critical-agent-policy.js
 src/agent/provider-control-plane.js

src/agent/agent-liveness-poll.js src/agent/agent-liveness-poll.tssrc/agent/agent-liveness-poll.js renamed to src/agent/agent-liveness-poll.ts

@@ -1,20 +1,90 @@
-const { isPlatformSupported } = require('./agent-stuck-detector');
+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) {
+function hasRecoverableTask(agent: LivenessAgent): boolean {
   return (
     Boolean(agent.currentTask) ||
     Boolean(agent.isolation?.enabled && agent.currentTaskId) ||
     agent.nestedExecutions?.hasActive === true
   );
 }
 
-function handlePendingTermination(agent, settings, now, attemptTermination) {
+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, now) {
+function taskTiming(agent: LivenessAgent, now: number): TaskTiming {
   const taskStartedAt = agent.taskStartedAt || agent.lastOutputTime || now;
   const lastOutputTime = agent.lastOutputTime || taskStartedAt;
   return {
@@ -24,7 +94,7 @@ function taskTiming(agent, now) {
   };
 }
 
-function handleTaskTimeout(context, timing) {
+function handleTaskTimeout(context: LivenessPollContext, timing: TaskTiming): boolean {
   const { agent, settings, configuredTimeout, beginTermination } = context;
   if (!configuredTimeout || timing.taskRuntime < configuredTimeout) return false;
   beginTermination(
@@ -41,7 +111,7 @@ function handleTaskTimeout(context, timing) {
   return true;
 }
 
-function publishStaleWarning(context, timing) {
+function publishStaleWarning(context: LivenessPollContext, timing: TaskTiming): void {
   const { agent, staleDuration, warningsBeforeKill } = context;
   agent.consecutiveStaleWarnings += 1;
   agent._publishLifecycle('AGENT_STALE_WARNING', {
@@ -56,7 +126,7 @@ function publishStaleWarning(context, timing) {
   });
 }
 
-function terminateForInactivity(context, timing) {
+function terminateForInactivity(context: LivenessPollContext, timing: TaskTiming): void {
   const { agent, settings, staleDuration, beginTermination } = context;
   beginTermination(
     agent,
@@ -72,7 +142,7 @@ function terminateForInactivity(context, timing) {
   );
 }
 
-function createLivenessPoll(context) {
+function createLivenessPoll(context: LivenessPollContext): () => void {
   const { agent, settings, staleDuration, warningsBeforeKill, attemptTermination } = context;
   return () => {
     if (!hasRecoverableTask(agent) || agent.livenessTerminationStarted) return;
@@ -90,4 +160,4 @@ function createLivenessPoll(context) {
   };
 }
 
-module.exports = { createLivenessPoll };
+export = { createLivenessPoll };

src/agent/agent-quality-gate-schema.js src/agent/agent-quality-gate-schema.tssrc/agent/agent-quality-gate-schema.js renamed to src/agent/agent-quality-gate-schema.ts

@@ -1,4 +1,37 @@
-function buildQualityGateSchema() {
+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.',
@@ -59,17 +92,17 @@ function buildQualityGateSchema() {
   };
 }
 
-function hasRequiredQualityGates(config) {
+function hasRequiredQualityGates(config: AgentQualityGateConfig): boolean {
   return Array.isArray(config.requiredQualityGates) && config.requiredQualityGates.length > 0;
 }
 
-function shouldApplyValidatorQualityGateDefaults(config) {
+function shouldApplyValidatorQualityGateDefaults(config: AgentQualityGateConfig): boolean {
   return (
     config.role === 'validator' && config.outputFormat === 'json' && hasRequiredQualityGates(config)
   );
 }
 
-function applyValidatorQualityGateSchema(config) {
+function applyValidatorQualityGateSchema(config: AgentQualityGateConfig): void {
   if (!shouldApplyValidatorQualityGateDefaults(config)) {
     return;
   }
@@ -80,7 +113,7 @@ function applyValidatorQualityGateSchema(config) {
   }
 }
 
-function applyValidatorQualityGatePublishMapping(config) {
+function applyValidatorQualityGatePublishMapping(config: AgentQualityGateConfig): void {
   if (!shouldApplyValidatorQualityGateDefaults(config)) {
     return;
   }
@@ -91,12 +124,12 @@ function applyValidatorQualityGatePublishMapping(config) {
   }
 }
 
-function applyValidatorQualityGateDefaults(config) {
+function applyValidatorQualityGateDefaults(config: AgentQualityGateConfig): void {
   applyValidatorQualityGateSchema(config);
   applyValidatorQualityGatePublishMapping(config);
 }
 
-module.exports = {
+export = {
   applyValidatorQualityGateDefaults,
   buildQualityGateSchema,
 };