@goodandready/dsh-agent-orchestrator 0.1.6

package/lib/routes.js

@@ -0,0 +1,277 @@
+/**
+ * HTTP REST API Routes for DSH Multi-Agent Orchestrator.
+ *
+ * Implements:
+ * - Fail-closed origin/host/loopback check on state mutating routes (/dispatch, /delegate, /cancel, /config, /snapshots/save-as-preset) (Issue #113)
+ * - Strict body payload limit (1MB max, 413 Payload Too Large on overflow) (Issue #113)
+ * - Safe read-only /status route (no mutations, public metrics only) (Issue #113)
+ * - Snapshots listing & One-Click Save as Preset (Issue #109)
+ */
+
+import { readModelSelection, fetchModelCatalog } from './pipeline/model-selection.js'
+import { executeDirectDelegation } from './pipeline/delegation.js'
+import { rejectUntrustedRequest, parseBoundedJsonBody } from './http-guard.js'
+import { SnapshotManager } from './pipeline/snapshots.js'
+import { validateScenario } from './pipeline/scenarios.js'
+
+function jsonReply(res, data, status = 200) {
+  res.statusCode = status
+  res.setHeader('Content-Type', 'application/json; charset=utf-8')
+  res.end(JSON.stringify(data))
+}
+
+export function registerOrchestratorRoutes(ctx, services) {
+  const { store, runner, getConfig, updateConfig, callLlm, snapshotManager = new SnapshotManager() } = services
+
+  // 1. Status & Global Metrics (Read-only status overview)
+  // Conscious architectural choice (Issue #113): Public read-only endpoint returning non-sensitive metrics
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/status',
+    handler: (req, res) => {
+      jsonReply(res, {
+        activePipelines: store.getActivePipelines(),
+        metrics: store.getMetrics(),
+        recentPipelines: store.getAllPipelines().slice(0, 10),
+      })
+    },
+  }), 'dsh-agent-orchestrator: status route')
+
+  // 2. Dispatch a new pipeline (multi-stage DAG) - Guarded (Issue #113)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/dispatch',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        return jsonReply(res, { error: 'Method not allowed' }, 405)
+      }
+      if (rejectUntrustedRequest(req, res)) return
+
+      let body
+      try {
+        body = await parseBoundedJsonBody(req)
+      } catch (err) {
+        return jsonReply(res, { error: err.message }, err.statusCode || 400)
+      }
+
+      try {
+        const pipeline = await runner.startPipeline({
+          taskTitle: body.taskTitle || body.title || 'Manual Pipeline Run',
+          taskDescription: body.taskDescription || body.description || body.prompt || '',
+          scenarioId: body.scenarioId || 'auto',
+          taskId: body.taskId, // optional linked kanban task
+        })
+        jsonReply(res, { success: true, pipeline })
+      } catch (err) {
+        jsonReply(res, { error: err?.message || String(err) }, 400)
+      }
+    },
+  }), 'dsh-agent-orchestrator: dispatch route')
+
+  // 3. Direct Specialist Delegation (single subagent) - Guarded (Issue #113)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/delegate',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        return jsonReply(res, { error: 'Method not allowed' }, 405)
+      }
+      if (rejectUntrustedRequest(req, res)) return
+
+      let body
+      try {
+        body = await parseBoundedJsonBody(req)
+      } catch (err) {
+        return jsonReply(res, { error: err.message }, err.statusCode || 400)
+      }
+
+      if (!body.task) {
+        return jsonReply(res, { error: 'Missing required field: task' }, 400)
+      }
+
+      try {
+        const selection = readModelSelection(ctx)
+        const result = await executeDirectDelegation({
+          roleId: body.roleId || 'architecture',
+          task: body.task,
+          context: body.context || '',
+          roles: getConfig().roles,
+          config: getConfig(),
+          callLlm,
+          allowedRoutes: selection.allowedRoutes,
+        })
+        jsonReply(res, { success: true, deliverable: result })
+      } catch (err) {
+        jsonReply(res, { error: err?.message || String(err) }, 500)
+      }
+    },
+  }), 'dsh-agent-orchestrator: direct delegate route')
+
+  // 4. Pipeline details by ID
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: '/dsh-agent-orchestrator/pipeline',
+    handler: (req, res) => {
+      const parts = req.url.split('?')[0].split('/')
+      const pipelineId = parts[parts.length - 1]
+      const pipeline = store.getPipeline(pipelineId)
+      if (!pipeline) {
+        return jsonReply(res, { error: 'Pipeline not found' }, 404)
+      }
+      jsonReply(res, { pipeline })
+    },
+  }), 'dsh-agent-orchestrator: pipeline detail route')
+
+  // 4b. Cancel a running pipeline - Guarded (Issue #113)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/cancel',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        return jsonReply(res, { error: 'Method not allowed' }, 405)
+      }
+      if (rejectUntrustedRequest(req, res)) return
+
+      let body
+      try {
+        body = await parseBoundedJsonBody(req)
+      } catch (err) {
+        return jsonReply(res, { error: err.message }, err.statusCode || 400)
+      }
+
+      const pipelineId = body.pipelineId
+      const p = store.getPipeline(pipelineId)
+      if (p && (p.status === 'running' || p.status === 'pending')) {
+        store.updatePipeline(pipelineId, {
+          status: 'failed',
+          completedAt: Date.now(),
+          error: 'Cancelled by user',
+        })
+        return jsonReply(res, { success: true })
+      }
+      jsonReply(res, { success: false, error: 'Pipeline not running or not found' }, 404)
+    },
+  }), 'dsh-agent-orchestrator: cancel route')
+
+  // 5. Configuration (roles, scenarios, kanbanSync) - Guarded (Issue #113)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/config',
+    handler: async (req, res) => {
+      if (req.method === 'POST') {
+        if (rejectUntrustedRequest(req, res)) return
+        let body
+        try {
+          body = await parseBoundedJsonBody(req)
+        } catch (err) {
+          return jsonReply(res, { error: err.message }, err.statusCode || 400)
+        }
+        if (body?.scenarios && typeof body.scenarios === 'object') {
+          for (const [sId, sc] of Object.entries(body.scenarios)) {
+            try {
+              validateScenario(sc)
+            } catch (vErr) {
+              return jsonReply(res, { error: `Invalid scenario "${sId}": ${vErr.message}` }, 400)
+            }
+          }
+        }
+        await updateConfig(body)
+        return jsonReply(res, { success: true, config: getConfig() })
+      }
+      jsonReply(res, { config: getConfig() })
+    },
+  }), 'dsh-agent-orchestrator: config route')
+
+  // 6. Available models query with allowedModels integration
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/models',
+    handler: async (req, res) => {
+      const selection = readModelSelection(ctx)
+      const catalog = await fetchModelCatalog(ctx, {
+        allowedRoutes: selection.allowedRoutes,
+      })
+
+      jsonReply(res, {
+        models: catalog,
+        authorizedConstraint: Boolean(selection.allowedRoutes && selection.allowedRoutes.length > 0),
+      })
+    },
+  }), 'dsh-agent-orchestrator: models route')
+
+  // 6b. Live Model & Subagent Catalog query (Issue #76)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/catalog/models',
+    handler: async (req, res) => {
+      try {
+        const urlObj = new URL(req.url, 'http://localhost')
+        const provider = urlObj.searchParams.get('provider') || undefined
+        const capability = urlObj.searchParams.get('capability') || undefined
+
+        const catalog = await fetchModelCatalog(ctx, { provider, capability })
+        jsonReply(res, {
+          total: catalog.length,
+          catalog,
+        })
+      } catch (err) {
+        jsonReply(res, { error: err?.message || String(err) }, 500)
+      }
+    },
+  }), 'dsh-agent-orchestrator: catalog models route')
+
+  // 7. Dispatch Snapshots Listing (Issue #109)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/snapshots',
+    handler: (req, res) => {
+      try {
+        const snapshots = snapshotManager.listSnapshots()
+        jsonReply(res, { snapshots, total: snapshots.length })
+      } catch (err) {
+        jsonReply(res, { error: err?.message || String(err) }, 500)
+      }
+    },
+  }), 'dsh-agent-orchestrator: snapshots list route')
+
+  // 8. One-Click Save as Preset (Issue #109) - Guarded (Issue #113)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-agent-orchestrator/snapshots/save-as-preset',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        return jsonReply(res, { error: 'Method not allowed' }, 405)
+      }
+      if (rejectUntrustedRequest(req, res)) return
+
+      let body
+      try {
+        body = await parseBoundedJsonBody(req)
+      } catch (err) {
+        return jsonReply(res, { error: err.message }, err.statusCode || 400)
+      }
+
+      const { snapshotId, name, description } = body || {}
+      if (!snapshotId) {
+        return jsonReply(res, { error: 'Missing required field: snapshotId' }, 400)
+      }
+      if (typeof snapshotId !== 'string' || !/^[a-zA-Z0-9_-]{1,64}$/.test(snapshotId)) {
+        return jsonReply(res, { error: 'Invalid or unsafe snapshotId' }, 400)
+      }
+
+      try {
+        const preset = snapshotManager.saveAsPreset(snapshotId, { name, description })
+        validateScenario(preset)
+
+        // Idempotently persist to configured scenarios
+        const currentScenarios = getConfig().scenarios || {}
+        currentScenarios[preset.id] = preset
+        await updateConfig({ scenarios: currentScenarios })
+
+        jsonReply(res, { success: true, preset })
+      } catch (err) {
+        jsonReply(res, { error: err?.message || String(err) }, 400)
+      }
+    },
+  }), 'dsh-agent-orchestrator: save-as-preset route')
+}

package/lib/store.js

@@ -0,0 +1,176 @@
+/**
+ * Pipeline & Metrics Store for DSH Multi-Agent Orchestrator.
+ *
+ * In-memory state with JSON persistence for recovery across turns.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+
+export class OrchestratorStore {
+  constructor(options = {}) {
+    const opts = typeof options === 'string' ? { storageDir: options } : (options || {})
+    const baseDir = opts.storageDir || join(homedir(), '.dsh')
+    this.storagePath = join(baseDir, 'orchestrator-pipelines.json')
+    this.logger = opts.logger || null
+    this.pipelines = new Map()
+    this.globalMetrics = {
+      totalPipelines: 0,
+      completedPipelines: 0,
+      failedPipelines: 0,
+      totalPromptTokens: 0,
+      totalCacheHitTokens: 0,
+      totalCacheMissTokens: 0,
+      overallHitRatio: 0,
+      totalDurationMs: 0,
+    }
+    this._load()
+  }
+
+  _load() {
+    try {
+      if (existsSync(this.storagePath)) {
+        const raw = readFileSync(this.storagePath, 'utf8')
+        const data = JSON.parse(raw)
+        if (Array.isArray(data.pipelines)) {
+          for (const p of data.pipelines) {
+            this.pipelines.set(p.pipelineId, p)
+          }
+        }
+        if (data.globalMetrics) {
+          this.globalMetrics = { ...this.globalMetrics, ...data.globalMetrics }
+        }
+      }
+    } catch (e) {
+      if (this.logger?.warn) this.logger.warn('[dsh-agent-orchestrator] Store load warning:', e?.message || e)
+    }
+  }
+
+  save() {
+    try {
+      mkdirSync(dirname(this.storagePath), { recursive: true })
+      const serialized = {
+        pipelines: Array.from(this.pipelines.values()).slice(-50), // keep last 50
+        globalMetrics: this.globalMetrics,
+        updatedAt: Date.now(),
+      }
+      writeFileSync(this.storagePath, JSON.stringify(serialized, null, 2), 'utf8')
+    } catch (e) {
+      if (this.logger?.warn) this.logger.warn('[dsh-agent-orchestrator] Store save warning:', e?.message || e)
+    }
+  }
+
+  recordPipeline(pipelineData) {
+    this.pipelines.set(pipelineData.pipelineId, pipelineData)
+    this.globalMetrics.totalPipelines++
+    this.save()
+  }
+
+  updatePipeline(pipelineId, updateFnOrPartial) {
+    const existing = this.pipelines.get(pipelineId)
+    if (existing) {
+      const updated = typeof updateFnOrPartial === 'function'
+        ? (updateFnOrPartial(existing) || existing)
+        : { ...existing, ...updateFnOrPartial }
+      this.pipelines.set(pipelineId, updated)
+
+      if (updated.status === 'completed' && existing.status !== 'completed') {
+        this.globalMetrics.completedPipelines++
+        this.globalMetrics.totalDurationMs += (updated.durationMs || 0)
+      } else if (updated.status === 'failed' && existing.status !== 'failed') {
+        this.globalMetrics.failedPipelines++
+      }
+
+      this.save()
+      return updated
+    }
+    return null
+  }
+
+  updateStage(pipelineId, stageId, updateFnOrPartial) {
+    const pipeline = this.pipelines.get(pipelineId)
+    if (!pipeline) return null
+
+    if (!pipeline.stateMap) pipeline.stateMap = {}
+    const existing = pipeline.stateMap[stageId] || { id: stageId, status: 'pending' }
+    const updated = typeof updateFnOrPartial === 'function'
+      ? (updateFnOrPartial(existing) || existing)
+      : { ...existing, ...updateFnOrPartial }
+
+    pipeline.stateMap[stageId] = updated
+
+    if (Array.isArray(pipeline.stages)) {
+      const idx = pipeline.stages.findIndex((s) => s.id === stageId)
+      if (idx !== -1) {
+        pipeline.stages[idx] = { ...pipeline.stages[idx], ...updated }
+      }
+    }
+
+    this.save()
+    return updated
+  }
+
+  appendStageLog(pipelineId, stageId, logDelta) {
+    const pipeline = this.pipelines.get(pipelineId)
+    if (!pipeline) return
+    if (!pipeline.stageLogs) pipeline.stageLogs = {}
+    if (!pipeline.stageLogs[stageId]) pipeline.stageLogs[stageId] = ''
+    pipeline.stageLogs[stageId] += String(logDelta || '')
+  }
+
+  recordCompletion(pipelineId, summary) {
+    const p = this.pipelines.get(pipelineId)
+    if (p) {
+      p.status = summary.success ? 'completed' : 'failed'
+      p.completedAt = Date.now()
+      p.durationMs = summary.durationMs || 0
+      p.stateMap = summary.stateMap || {}
+      p.artifacts = summary.artifacts || {}
+
+      if (summary.success) {
+        this.globalMetrics.completedPipelines++
+      } else {
+        this.globalMetrics.failedPipelines++
+      }
+
+      this.globalMetrics.totalDurationMs += p.durationMs
+
+      // Aggregate cache metrics across all stages
+      for (const node of Object.values(summary.stateMap || {})) {
+        const m = node.metrics
+        if (m) {
+          this.globalMetrics.totalPromptTokens += m.promptTokens || 0
+          this.globalMetrics.totalCacheHitTokens += m.cacheHitTokens || 0
+          this.globalMetrics.totalCacheMissTokens += m.cacheMissTokens || 0
+        }
+      }
+
+      if (this.globalMetrics.totalPromptTokens > 0) {
+        this.globalMetrics.overallHitRatio = parseFloat(
+          (this.globalMetrics.totalCacheHitTokens / this.globalMetrics.totalPromptTokens).toFixed(4)
+        )
+      }
+
+      this.save()
+    }
+  }
+
+  getPipeline(pipelineId) {
+    return this.pipelines.get(pipelineId) || null
+  }
+
+  getActivePipelines() {
+    return Array.from(this.pipelines.values()).filter(
+      (p) => p.status === 'running' || p.status === 'pending'
+    )
+  }
+
+  getAllPipelines() {
+    return Array.from(this.pipelines.values()).sort((a, b) => b.createdAt - a.createdAt)
+  }
+
+  getMetrics() {
+    return { ...this.globalMetrics }
+  }
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@goodandready/dsh-agent-orchestrator",
+  "version": "0.1.6",
+  "description": "Multi-agent task decomposition, DAG workflow orchestration, and prompt caching optimizer for DeepSeek Harness.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.ru.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "orchestrator",
+    "multi-agent",
+    "prompt-caching",
+    "dag-workflow",
+    "kanban"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GooDAnDReaDY/dsh-agent-orchestrator.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-agent-orchestrator#readme",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-agent-orchestrator/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.6 <1.0.0",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.6 <1.0.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.6 <1.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6 <1.0.0",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.6 <1.0.0",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}