@goodandready/dsh-agent-orchestrator 0.1.6

package/lib/pipeline/snapshots.js

@@ -0,0 +1,240 @@
+/**
+ * Dispatch Snapshots & One-Click Save as Preset Engine (Issue #109).
+ * Security Hardened against Path Traversal (Issue #135).
+ * Migrated to ctx.logger (Issue #130).
+ *
+ * Implements:
+ * 1. Atomic snapshot storage in ~/.dsh/orchestrator-snapshots/ (or configured dir).
+ * 2. FIFO retention policy with a 200-item hard ceiling.
+ * 3. Atomic writes via .tmp files and atomic rename to prevent corruption.
+ * 4. Save as Preset method for turning any completed dispatch run into a reusable preset.
+ * 5. Strict path traversal verification and snapshot ID sanitization.
+ */
+
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { randomUUID } from 'crypto'
+
+export const DEFAULT_MAX_SNAPSHOTS = 200
+
+export class SnapshotManager {
+  constructor({ baseDir, maxSnapshots = DEFAULT_MAX_SNAPSHOTS, logger } = {}) {
+    this.baseDir = baseDir || path.join(os.homedir(), '.dsh', 'orchestrator-snapshots')
+    this.maxSnapshots = maxSnapshots
+    this.logger = logger || null
+    this._ensureDir()
+  }
+
+  _ensureDir() {
+    try {
+      if (!fs.existsSync(this.baseDir)) {
+        fs.mkdirSync(this.baseDir, { recursive: true })
+      }
+    } catch (err) {
+      if (this.logger?.error) {
+        this.logger.error(`[SnapshotManager] Failed to create baseDir ${this.baseDir}:`, err?.message || err)
+      }
+    }
+  }
+
+  /**
+   * Resolves and verifies that a snapshotId stays strictly within baseDir.
+   * @param {string} snapshotId
+   * @returns {string} Absolute resolved file path
+   * @throws {Error} If snapshotId contains illegal characters, path separators, or escapes baseDir
+   */
+  _pathFor(snapshotId) {
+    if (!snapshotId || typeof snapshotId !== 'string') {
+      throw new Error('Invalid snapshotId: must be a non-empty string')
+    }
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(snapshotId)) {
+      throw new Error(`Invalid snapshotId: "${snapshotId}" contains illegal characters or invalid length`)
+    }
+    const baseResolved = path.resolve(this.baseDir)
+    const resolved = path.resolve(this.baseDir, `${snapshotId}.json`)
+    if (!resolved.startsWith(baseResolved + path.sep)) {
+      throw new Error(`Path traversal attempt detected in snapshotId: "${snapshotId}"`)
+    }
+    return resolved
+  }
+
+  /**
+   * Lists all recorded snapshots sorted newest to oldest.
+   * @returns {Array<object>}
+   */
+  listSnapshots() {
+    this._ensureDir()
+    try {
+      const files = fs.readdirSync(this.baseDir)
+      const snapshots = []
+
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue
+        const filePath = path.join(this.baseDir, file)
+        try {
+          const content = fs.readFileSync(filePath, 'utf8')
+          const data = JSON.parse(content)
+          snapshots.push(data)
+        } catch (err) {
+          // Ignore corrupt files during listing
+          if (this.logger?.warn) {
+            this.logger.warn(`[SnapshotManager] Skipping invalid snapshot file ${file}:`, err?.message || err)
+          }
+        }
+      }
+
+      // Sort descending by timestamp / createdAt
+      snapshots.sort((a, b) => {
+        const timeA = new Date(a.createdAt || a.timestamp || 0).getTime()
+        const timeB = new Date(b.createdAt || b.timestamp || 0).getTime()
+        return timeB - timeA
+      })
+
+      return snapshots
+    } catch (err) {
+      if (this.logger?.error) {
+        this.logger.error('[SnapshotManager] Error listing snapshots:', err?.message || err)
+      }
+      return []
+    }
+  }
+
+  /**
+   * Retrieves a snapshot by ID with path traversal protection.
+   * @param {string} snapshotId
+   * @returns {object|null}
+   */
+  getSnapshot(snapshotId) {
+    if (!snapshotId) return null
+    let filePath
+    try {
+      filePath = this._pathFor(snapshotId)
+    } catch (err) {
+      if (this.logger?.warn) {
+        this.logger.warn(`[SnapshotManager] Invalid snapshotId rejected: ${err?.message || err}`)
+      }
+      return null
+    }
+
+    if (!fs.existsSync(filePath)) return null
+    try {
+      const content = fs.readFileSync(filePath, 'utf8')
+      return JSON.parse(content)
+    } catch (err) {
+      if (this.logger?.error) {
+        this.logger.error(`[SnapshotManager] Error reading snapshot ${snapshotId}:`, err?.message || err)
+      }
+      return null
+    }
+  }
+
+  /**
+   * Creates a snapshot atomically with path traversal protection.
+   * @param {object} snapshotData
+   * @returns {object} The created snapshot metadata
+   */
+  createSnapshot(snapshotData = {}) {
+    this._ensureDir()
+
+    const snapshotId = snapshotData.id || `snap-${Date.now()}-${randomUUID().slice(0, 8)}`
+    const filePath = this._pathFor(snapshotId)
+    const nowIso = new Date().toISOString()
+
+    const record = {
+      id: snapshotId,
+      createdAt: nowIso,
+      title: snapshotData.title || `Snapshot ${snapshotId}`,
+      scenarioId: snapshotData.scenarioId || 'custom',
+      status: snapshotData.status || 'completed',
+      modelOverrides: snapshotData.modelOverrides || {},
+      stages: snapshotData.stages || [],
+      roles: snapshotData.roles || [],
+      totalCostUsd: snapshotData.totalCostUsd || 0,
+      durationMs: snapshotData.durationMs || 0,
+      metadata: snapshotData.metadata || {},
+    }
+
+    const tmpPath = path.join(this.baseDir, `${snapshotId}.tmp-${Date.now()}`)
+
+    try {
+      fs.writeFileSync(tmpPath, JSON.stringify(record, null, 2), 'utf8')
+      fs.renameSync(tmpPath, filePath)
+    } catch (err) {
+      try {
+        if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath)
+      } catch (_) {
+        // Safe ignore
+      }
+      throw err
+    }
+
+    // Enforce FIFO retention policy: if file count > maxSnapshots, prune oldest
+    this._enforceRetention()
+
+    return record
+  }
+
+  /**
+   * Prunes oldest snapshot files when total exceeds maxSnapshots ceiling.
+   */
+  _enforceRetention() {
+    try {
+      const files = fs.readdirSync(this.baseDir).filter((f) => f.endsWith('.json'))
+      if (files.length <= this.maxSnapshots) return
+
+      const fileStats = files.map((file) => {
+        const fullPath = path.join(this.baseDir, file)
+        const stat = fs.statSync(fullPath)
+        return { file, fullPath, mtime: stat.mtimeMs }
+      })
+
+      // Sort ascending (oldest first)
+      fileStats.sort((a, b) => a.mtime - b.mtime)
+
+      const removeCount = fileStats.length - this.maxSnapshots
+      for (let i = 0; i < removeCount; i++) {
+        try {
+          fs.unlinkSync(fileStats[i].fullPath)
+        } catch (err) {
+          if (this.logger?.warn) {
+            this.logger.warn(`[SnapshotManager] Failed to prune old snapshot ${fileStats[i].file}:`, err?.message || err)
+          }
+        }
+      }
+    } catch (err) {
+      if (this.logger?.warn) {
+        this.logger.warn('[SnapshotManager] Retention enforcement error:', err?.message || err)
+      }
+    }
+  }
+
+  /**
+   * Converts a snapshot into a reusable scenario/preset structure.
+   * @param {string} snapshotId
+   * @param {object} [overrides] Custom name/description
+   * @returns {object} Preset configuration object
+   */
+  saveAsPreset(snapshotId, overrides = {}) {
+    this._pathFor(snapshotId)
+    const snapshot = this.getSnapshot(snapshotId)
+    if (!snapshot) {
+      throw new Error(`Snapshot "${snapshotId}" not found`)
+    }
+
+    const presetId = overrides.id || `preset-${snapshot.scenarioId || 'custom'}-${Date.now().toString(36)}`
+    const presetName = overrides.name || overrides.title || `Preset from ${snapshot.title || snapshotId}`
+    const presetDescription = overrides.description || `Generated from snapshot ${snapshotId} at ${new Date().toISOString()}`
+
+    return {
+      id: presetId,
+      name: presetName,
+      description: presetDescription,
+      scenarioId: snapshot.scenarioId || 'custom',
+      stages: snapshot.stages || [],
+      modelOverrides: snapshot.modelOverrides || {},
+      createdAt: new Date().toISOString(),
+      sourceSnapshotId: snapshotId,
+    }
+  }
+}

package/lib/pipeline/token-watchdog.js

@@ -0,0 +1,101 @@
+/**
+ * Deterministic Max-Tokens Watchdog.
+ *
+ * Implements Issue #75:
+ * 1. Turn-end interception when output is truncated due to max-tokens limit.
+ * 2. Flush Checkpoint: flushes state to prevent lost progress.
+ * 3. Continue-Once Guarantee: strictly allows at most ONE automated continuation per execution.
+ * 4. Cycle Protection: if truncation occurs again, halts with MaxTokensLoopError demanding
+ *    subtask decomposition, preventing infinite loops and token drain.
+ */
+
+export class MaxTokensLoopError extends Error {
+  constructor(message, { executionId, continuationCount = 1 } = {}) {
+    super(message)
+    this.name = 'MaxTokensLoopError'
+    this.executionId = executionId
+    this.continuationCount = continuationCount
+  }
+}
+
+/**
+ * Checks whether a given stop reason or response indicates token limit exhaustion.
+ *
+ * @param {string|object} stopReason
+ * @returns {boolean}
+ */
+export function isMaxTokensTruncated(stopReason) {
+  if (!stopReason) return false
+  if (typeof stopReason === 'object') {
+    if (stopReason.kind === 'max-tokens' || stopReason.kind === 'length') return true
+    if (stopReason.stopReason === 'max_tokens' || stopReason.stopReason === 'length') return true
+    return false
+  }
+
+  const s = String(stopReason).toLowerCase()
+  return s === 'max-tokens' || s === 'max_tokens' || s === 'length' || s.includes('token_limit')
+}
+
+/**
+ * Wraps a turn / worker execution with Deterministic max-tokens Watchdog.
+ *
+ * @param {object} params
+ * @param {function} params.executeTurn Function (continuationCount) => Promise<{ output: string, stopReason: string, raw?: any }>
+ * @param {function} [params.flushCheckpoint] Callback to persist session checkpoint before continuation
+ * @param {string} [params.continuationPrompt='Continue generation precisely from where you stopped.']
+ * @param {string} [params.executionId]
+ * @returns {Promise<{ output: string, stopReason: string, continuationCount: number, wasTruncated: boolean }>}
+ */
+export async function runWithMaxTokensWatchdog({
+  executeTurn,
+  flushCheckpoint,
+  continuationPrompt = 'Continue generation precisely from where you stopped.',
+  executionId = 'turn',
+  logger = null,
+}) {
+  let continuationCount = 0
+  let combinedOutput = ''
+
+  // Step 1: Initial turn
+  const initialResult = await executeTurn(0, '')
+  combinedOutput = initialResult.output || ''
+
+  if (!isMaxTokensTruncated(initialResult.stopReason)) {
+    return {
+      output: combinedOutput,
+      stopReason: initialResult.stopReason || 'completed',
+      continuationCount: 0,
+      wasTruncated: false,
+    }
+  }
+
+  // Step 2: First truncation detected -> trigger single automated continuation
+  continuationCount = 1
+
+  if (typeof flushCheckpoint === 'function') {
+    try {
+      await flushCheckpoint()
+    } catch (err) {
+      if (logger?.debug) logger.debug('[MaxTokensWatchdog] flushCheckpoint warning:', err?.message || err)
+    }
+  }
+
+  const secondResult = await executeTurn(continuationCount, continuationPrompt)
+  combinedOutput += (combinedOutput ? '\n' : '') + (secondResult.output || '')
+
+  // Step 3: Cycle Protection Check (Continue-Once Guarantee)
+  if (isMaxTokensTruncated(secondResult.stopReason)) {
+    throw new MaxTokensLoopError(
+      `[MaxTokensWatchdog] Task "${executionId}" truncated by token limit twice. ` +
+      `Automated continuation aborted to prevent infinite token consumption. Please decompose the task into smaller subtasks.`,
+      { executionId, continuationCount }
+    )
+  }
+
+  return {
+    output: combinedOutput,
+    stopReason: secondResult.stopReason || 'completed',
+    continuationCount,
+    wasTruncated: true,
+  }
+}

package/lib/pipeline/worker-pool.js

@@ -0,0 +1,143 @@
+/**
+ * Worker Pool Dispatcher for DSH Multi-Agent Orchestrator.
+ *
+ * Dispatches stage executions to LLM instances with:
+ * - Canonical prefix alignment (Prompt Caching maximization)
+ * - Transient retry handling (HTTP 429, network timeouts)
+ * - Streaming token collection
+ * - Telemetry recording (Cache Hit ratio, duration, token usage)
+ */
+
+import {
+  buildStaticBaseAnchor,
+  buildSharedTaskAnchor,
+  formatCumulativeArtifacts,
+  assembleAgentMessages,
+  extractCacheMetrics,
+} from './cache-prefixer.js'
+import { resolveSpecialistModel } from './model-selection.js'
+
+/**
+ * Invokes LLM with exponential backoff on recoverable transient errors.
+ */
+export async function callWithTransientRetry(callLlmFn, args, maxRetries = 2, baseDelayMs = 1500) {
+  let attempt = 0
+  while (true) {
+    try {
+      return await callLlmFn(args)
+    } catch (err) {
+      attempt++
+      const msg = err?.message || String(err)
+      const isTransient = /429|rate limit|quota|502|503|504|econnreset|etimedout|socket hang up/i.test(msg)
+      if (attempt <= maxRetries && isTransient) {
+        const delay = baseDelayMs * Math.pow(2, attempt - 1)
+        await new Promise((r) => setTimeout(r, delay))
+        continue
+      }
+      throw err
+    }
+  }
+}
+
+/**
+ * Executes a single pipeline stage with full prompt cache alignment.
+ *
+ * @param {object} stage Stage definition
+ * @param {object} context Execution context
+ * @param {object} context.pipeline Global pipeline metadata
+ * @param {object} context.agentRole Configured role for this stage
+ * @param {object} context.config Plugin configuration
+ * @param {function} context.callLlm Function to call DSH LLM
+ * @param {object} context.upstreamOutputs Prior stage outputs map
+ * @param {function} [context.onStreamDelta] Streaming callback
+ * @returns {Promise<{ output: string, metrics: object }>}
+ */
+export async function executeStageWorker(stage, context) {
+  const { pipeline, agentRole, config = {}, callLlm, upstreamOutputs = {}, onStreamDelta } = context
+
+  if (typeof callLlm !== 'function') {
+    throw new Error('callLlm function is required to execute stage worker')
+  }
+
+  // 1. Build Layer 1: Static Base Anchor (> 1024 tokens)
+  const baseAnchor = buildStaticBaseAnchor({
+    projectType: config.projectType || 'dsh-plugin',
+    customRules: config.customRules || '',
+  })
+
+  // 2. Build Layer 2: Shared Task Anchor
+  const taskAnchor = buildSharedTaskAnchor({
+    id: pipeline.pipelineId,
+    title: pipeline.taskTitle,
+    description: pipeline.taskDescription,
+    repo: pipeline.repo,
+    issueUrl: pipeline.issueUrl,
+    scenario: pipeline.scenarioId,
+  })
+
+  // 3. Build Layer 3: Cumulative Upstream Artifacts (Append-Only)
+  const priorArtifactsList = []
+  for (const [depId, artContent] of Object.entries(upstreamOutputs)) {
+    priorArtifactsList.push({
+      stageId: depId,
+      roleId: stage.dependsOn?.find((d) => d === depId) || 'upstream',
+      output: artContent || '',
+    })
+  }
+  const cumulativeArtifacts = formatCumulativeArtifacts(priorArtifactsList)
+
+  // 4. Assemble canonical prompt (Layer 1 + 2 + 3 in System, Layer 4 in User)
+  const messages = assembleAgentMessages({
+    baseAnchor,
+    taskAnchor,
+    cumulativeArtifacts,
+    agentRole,
+    currentStage: stage,
+  })
+
+  const { provider, model, warning, maxTokens: resolvedMaxTokens, reasoningEffort } = resolveSpecialistModel({
+    roleModel: agentRole.defaultModel,
+    fallbackModel: { provider: 'deepseek', model: 'deepseek-chat' },
+    allowedRoutes: context.allowedRoutes,
+    capability: agentRole.capability,
+    reasoningEffort: agentRole.reasoningEffort,
+  })
+
+  const log = context.logger || context.config?.logger || null
+  if (warning && log?.warn) {
+    log.warn(`[dsh-agent-orchestrator] ${warning}`)
+  }
+
+  const temperature = agentRole.temperature ?? 0.3
+  const maxTokens = resolvedMaxTokens ?? agentRole.maxTokens ?? 4096
+
+  // 5. Execute LLM call with retry
+  const result = await callWithTransientRetry(
+    callLlm,
+    {
+      provider,
+      model,
+      messages,
+      temperature,
+      maxTokens,
+      reasoningEffort,
+      onStreamDelta,
+    },
+    2,
+    1200
+  )
+
+  const outputText = result.text || result.content || ''
+  const rawUsage = result.usage || {}
+  const cacheMetrics = extractCacheMetrics(rawUsage)
+
+  return {
+    output: outputText,
+    metrics: {
+      ...cacheMetrics,
+      model: `${provider}:${model}`,
+      stageId: stage.id,
+      roleId: stage.roleId,
+    },
+  }
+}