dsh-math-modeling-agent 0.1.0

package/skills/math-modeling-agent/schemas/ledger.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/yohanchen1/MathModelingAgent/schemas/ledger.schema.json",
+  "title": "Math Modeling Ledger",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "taskId",
+    "scope",
+    "assumptions",
+    "claims",
+    "obligations",
+    "subproblems",
+    "candidates",
+    "issues"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "taskId": {
+      "type": "string"
+    },
+    "scope": {
+      "type": "object"
+    },
+    "assumptions": {
+      "type": "array"
+    },
+    "claims": {
+      "type": "array"
+    },
+    "obligations": {
+      "type": "array"
+    },
+    "subproblems": {
+      "type": "array"
+    },
+    "candidates": {
+      "type": "array"
+    },
+    "issues": {
+      "type": "array"
+    }
+  }
+}

package/skills/math-modeling-agent/schemas/run.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/yohanchen1/MathModelingAgent/schemas/run.schema.json",
+  "title": "Math Modeling Run",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "taskId",
+    "mode",
+    "status",
+    "eventSequence",
+    "currentAttempt",
+    "bestCandidateId",
+    "budget",
+    "createdAt",
+    "updatedAt"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "taskId": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "mode": {
+      "enum": [
+        "fast",
+        "standard",
+        "high-assurance"
+      ]
+    },
+    "status": {
+      "enum": [
+        "TRIAGE",
+        "SCOPE_FROZEN",
+        "INPUT_PROFILED",
+        "CLAIMS_REGISTERED",
+        "CANDIDATES_READY",
+        "ATTEMPT",
+        "EXECUTE",
+        "VERIFY",
+        "REVISE",
+        "RESEARCH",
+        "FORK",
+        "SOLVED",
+        "PARTIAL",
+        "CONDITIONAL",
+        "INCONCLUSIVE",
+        "REFUTED",
+        "INFEASIBLE",
+        "UNIDENTIFIABLE",
+        "BLOCKED",
+        "CANCELLED"
+      ]
+    },
+    "eventSequence": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "currentAttempt": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "bestCandidateId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "attempts",
+        "researchQueries",
+        "computeSeconds"
+      ],
+      "properties": {
+        "attempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "researchQueries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "computeSeconds": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "createdAt": {
+      "type": "string"
+    },
+    "updatedAt": {
+      "type": "string"
+    }
+  }
+}

package/skills/math-modeling-agent/scripts/capability-probe.mjs

@@ -0,0 +1,105 @@
+import { accessSync, constants, existsSync, statSync } from 'node:fs'
+import { delimiter, extname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const REASON = 'Found on PATH; execute through the DSH shell to verify version and usability.'
+
+const TOOL_CANDIDATES = {
+  uv: ['uv'],
+  python: ['python3', 'python', 'py'],
+  lean: ['lean'],
+  lake: ['lake'],
+  wolfram: ['wolframscript', 'WolframScript'],
+}
+
+function executableExtensions(env, platform) {
+  if (platform !== 'win32') return ['']
+  const raw = env.PATHEXT || '.COM;.EXE;.BAT;.CMD'
+  return raw
+    .split(';')
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .map((value) => value.toLowerCase())
+}
+
+function candidateNames(name, extensions, platform) {
+  if (platform !== 'win32' || extname(name)) return [name]
+  return extensions.map((extension) => `${name}${extension}`)
+}
+
+function isExecutable(path, platform) {
+  if (!existsSync(path)) return false
+  try {
+    if (!statSync(path).isFile()) return false
+    accessSync(path, platform === 'win32' ? constants.F_OK : constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function findExecutable(names, options = {}) {
+  const env = options.env ?? process.env
+  const platform = options.platform ?? process.platform
+  const directories = (env.PATH ?? '').split(delimiter).filter(Boolean)
+  const extensions = executableExtensions(env, platform)
+
+  for (const directory of directories) {
+    for (const name of names) {
+      for (const candidate of candidateNames(name, extensions, platform)) {
+        const path = join(directory, candidate)
+        if (isExecutable(path, platform)) return path
+      }
+    }
+  }
+  return undefined
+}
+
+function toolRecord(key, names, options) {
+  const executable = findExecutable(names, options)
+  if (!executable) {
+    return {
+      status: 'unavailable',
+      executable: null,
+      kind: key,
+      reason: 'No candidate executable was found on PATH.',
+    }
+  }
+  return {
+    status: 'candidate',
+    executable,
+    kind: key,
+    reason: REASON,
+  }
+}
+
+export function probeCapabilities(options = {}) {
+  const env = options.env ?? process.env
+  const platform = options.platform ?? process.platform
+  return {
+    schemaVersion: 1,
+    platform,
+    node: {
+      status: 'available',
+      executable: process.execPath,
+      version: process.version,
+    },
+    tools: Object.fromEntries(
+      Object.entries(TOOL_CANDIDATES).map(([key, names]) => [
+        key,
+        toolRecord(key, names, { env, platform }),
+      ]),
+    ),
+  }
+}
+
+function main() {
+  const pretty = process.argv.includes('--pretty')
+  process.stdout.write(
+    `${JSON.stringify(probeCapabilities(), null, pretty ? 2 : 0)}
+`,
+  )
+}
+
+const invokedPath = process.argv[1]
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) main()

package/skills/math-modeling-agent/scripts/python-environment.mjs

@@ -0,0 +1,408 @@
+import { closeSync, openSync } from 'node:fs'
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { dirname, isAbsolute, posix, resolve, win32 } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
+
+const PACKAGE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(?:==[A-Za-z0-9][A-Za-z0-9._+-]*)?$/
+const REPAIR_GUIDANCE = 'Remove the inconsistent Python environment artifacts and retry.'
+
+export function validatePackageSpec(value) {
+  if (!PACKAGE_PATTERN.test(value)) throw new TypeError(`unsafe package spec: ${value}`)
+  return value
+}
+
+function environmentPython(environmentDir, platform, resolvePath) {
+  return platform === 'win32'
+    ? resolvePath(environmentDir, 'Scripts', 'python.exe')
+    : resolvePath(environmentDir, 'bin', 'python')
+}
+
+function temporaryPath(path) {
+  return `${path}.${process.pid}.${randomUUID()}.tmp`
+}
+
+async function atomicWriteJson(path, value, { renamePath = rename, removePath = rm } = {}) {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = temporaryPath(path)
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`)
+    await renamePath(temporary, path)
+  } catch (error) {
+    await removePath(temporary, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+export function defaultSpawnOptions({ cwd, stdoutDescriptor } = {}) {
+  return {
+    cwd,
+    shell: false,
+    stdio: ['ignore', stdoutDescriptor ?? 2, 2],
+  }
+}
+
+async function defaultRun(command, args, options = {}) {
+  let descriptor
+  try {
+    descriptor = options.stdoutFile ? openSync(options.stdoutFile, 'w') : undefined
+    const result = spawnSync(command, args, defaultSpawnOptions({
+      cwd: options.cwd,
+      stdoutDescriptor: descriptor,
+    }))
+    return result.status ?? 1
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor)
+  }
+}
+
+function assertSuccess(status, label) {
+  if (status !== 0) throw new Error(`${label} failed with exit code ${status}`)
+}
+
+function pathApi(platform) {
+  return platform === 'win32' ? win32 : posix
+}
+
+// Candidates come from the trusted PATH probe; PATH is intentionally user-controlled, and this CLI runs with that user's privileges.
+async function validateExecutable(record, kind, platform, fileStat) {
+  if (!record || record.status !== 'candidate' || !record.executable) return null
+  const api = pathApi(platform)
+  const executable = record.executable
+  const absolute = platform === process.platform ? isAbsolute(executable) : api.isAbsolute(executable)
+  if (!absolute) throw new Error(`${kind} candidate executable must be an absolute path`)
+  const basename = api.basename(executable).toLowerCase()
+  const allowed = kind === 'uv'
+    ? /^(uv)(?:\.exe)?$/
+    : /^(python|python3|py)(?:\.exe)?$/
+  if (!allowed.test(basename)) throw new Error(`${kind} candidate executable has an untrusted basename`)
+  let info
+  try {
+    info = await fileStat(executable)
+  } catch {
+    throw new Error(`${kind} candidate executable is not a regular file`)
+  }
+  if (!info.isFile()) throw new Error(`${kind} candidate executable is not a regular file`)
+  return { ...record, executable }
+}
+
+function pythonVenvArgs(record, environmentDir, platform) {
+  const name = pathApi(platform).basename(record.executable).toLowerCase()
+  if (name === 'py' || name === 'py.exe') return ['-3', '-m', 'venv', environmentDir]
+  return ['-m', 'venv', environmentDir]
+}
+
+async function exists(path, fileStat) {
+  try {
+    await fileStat(path)
+    return true
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function samePackages(left, right) {
+  return Array.isArray(left)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index])
+}
+
+async function readManifest(manifestPath) {
+  try {
+    return JSON.parse(await readFile(manifestPath, 'utf8'))
+  } catch {
+    throw new Error(`Python environment manifest is invalid. ${REPAIR_GUIDANCE}`)
+  }
+}
+
+function isBlockedManifest(manifest, environmentDir) {
+  return manifest?.status === 'blocked'
+    && manifest.adapter === null
+    && manifest.environmentDir === environmentDir
+    && manifest.python === null
+    && manifest.lockPath === null
+    && Array.isArray(manifest.requestedPackages)
+}
+
+function isReadyManifest(manifest, environmentDir, lockPath) {
+  return manifest?.status === 'ready'
+    && manifest.environmentDir === environmentDir
+    && manifest.lockPath === lockPath
+    && Array.isArray(manifest.requestedPackages)
+}
+
+async function inspectExisting({ environmentDir, manifestPath, lockPath, packages, fileStat }) {
+  const [hasEnvironment, hasManifest, hasLock] = await Promise.all([
+    exists(environmentDir, fileStat), exists(manifestPath, fileStat), exists(lockPath, fileStat),
+  ])
+  if (!hasEnvironment && !hasManifest && !hasLock) return null
+  if (hasManifest) {
+    const manifest = await readManifest(manifestPath)
+    if (isBlockedManifest(manifest, environmentDir)) {
+      if (hasEnvironment || hasLock) {
+        throw new Error(`Python environment is orphaned or inconsistent. ${REPAIR_GUIDANCE}`)
+      }
+      if (!samePackages(manifest.requestedPackages, packages)) {
+        throw new Error('Existing blocked Python environment uses a different package configuration; refusing to mutate it.')
+      }
+      return manifest
+    }
+    if (isReadyManifest(manifest, environmentDir, lockPath) && hasEnvironment && hasLock) {
+      if (!samePackages(manifest.requestedPackages, packages)) {
+        throw new Error('Existing ready Python environment uses a different package configuration; refusing to mutate it.')
+      }
+      return manifest
+    }
+  }
+  throw new Error(`Python environment is orphaned or inconsistent. ${REPAIR_GUIDANCE}`)
+}
+
+function defaultProcessAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error?.code === 'EPERM'
+  }
+}
+
+async function acquireLock({ lockDir, manifestPath, environmentDir, lockPath, packages, fileStat, now, processAlive, retryDelay, retryDelayMs, attempts, staleMs, renamePath, removePath }) {
+  const owner = { pid: process.pid, time: now(), id: randomUUID() }
+  let reclaimedDeadOwner = false
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    let created = false
+    try {
+      await mkdir(lockDir)
+      created = true
+      await atomicWriteJson(resolve(lockDir, 'owner.json'), owner, { renamePath, removePath })
+      return { owner, reclaimedDeadOwner }
+    } catch (error) {
+      if (!created && error?.code !== 'EEXIST') throw error
+      if (created && error?.code !== 'ENOENT' && error?.code !== 'EEXIST') throw error
+    }
+    let incumbent
+    try {
+      incumbent = JSON.parse(await readFile(resolve(lockDir, 'owner.json'), 'utf8'))
+    } catch {
+      incumbent = null
+    }
+    let lockAge = 0
+    try {
+      lockAge = now() - (await fileStat(lockDir)).mtimeMs
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue
+      throw error
+    }
+    const validOwner = incumbent && Number.isInteger(incumbent.pid) && Number.isFinite(incumbent.time)
+    const staleDeadOwner = validOwner && now() - incumbent.time >= staleMs && !processAlive(incumbent.pid)
+    const stalePartialOwner = !validOwner && lockAge >= staleMs
+    if (staleDeadOwner || stalePartialOwner) {
+      let mayReclaim = !await exists(manifestPath, fileStat)
+      if (!mayReclaim) {
+        const hasLock = await exists(lockDir, fileStat)
+        if (!hasLock) {
+          const existing = await inspectExisting({ environmentDir, manifestPath, lockPath, packages, fileStat })
+          mayReclaim = existing?.status === 'blocked'
+        } else {
+          const manifest = await readManifest(manifestPath)
+          mayReclaim = isBlockedManifest(manifest, environmentDir)
+        }
+      }
+      if (mayReclaim) {
+        const reclaimed = `${lockDir}.reclaimed.${owner.id}`
+        try {
+          await renamePath(lockDir, reclaimed)
+          await removePath(reclaimed, { recursive: true, force: true })
+          reclaimedDeadOwner = true
+          continue
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error
+        }
+      }
+    }
+    await retryDelay(retryDelayMs)
+  }
+  throw new Error('Timed out waiting for the Python environment lock.')
+}
+
+async function releaseLock(lockDir, owner, removePath) {
+  try {
+    const incumbent = JSON.parse(await readFile(resolve(lockDir, 'owner.json'), 'utf8'))
+    if (incumbent.id === owner.id) await removePath(lockDir, { recursive: true, force: true })
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+}
+
+function ensureContained(runDir, path, platform) {
+  const api = win32.isAbsolute(runDir) ? win32 : pathApi(platform)
+  const relative = api.relative(runDir, path)
+  if (relative === '' || (!relative.startsWith('..') && !api.isAbsolute(relative))) return path
+  throw new Error('Python environment path escapes the run directory.')
+}
+
+async function freezeRequirements(runCommand, pythonPath, executionPythonPath, runDir, stagedLockPath, finalLockPath, commands) {
+  const freezeArgs = ['-m', 'pip', 'freeze']
+  commands.push({ command: pythonPath, args: freezeArgs, stdoutFile: finalLockPath })
+  assertSuccess(
+    await runCommand(executionPythonPath, freezeArgs, { cwd: runDir, stdoutFile: stagedLockPath }),
+    'pip freeze',
+  )
+}
+
+export async function createPythonEnvironment(input) {
+  const platform = input.platform ?? process.platform
+  const resolvePath = input.resolvePath ?? resolve
+  const runDir = resolvePath(input.runDir)
+  const environmentDir = ensureContained(runDir, resolvePath(runDir, '.python-env'), platform)
+  const lockPath = ensureContained(runDir, resolvePath(runDir, 'requirements.lock'), platform)
+  const manifestPath = ensureContained(runDir, resolvePath(runDir, 'python-environment.json'), platform)
+  const transactionLockDir = ensureContained(runDir, resolvePath(runDir, '.python-environment.lock'), platform)
+  const packages = input.packages.map(validatePackageSpec)
+  const runCommand = input.runCommand ?? defaultRun
+  const fileStat = input.fileStat ?? stat
+  const renamePath = input.renamePath ?? rename
+  const removePath = input.removePath ?? rm
+  const retryDelay = input.retryDelay ?? ((milliseconds) => new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds)))
+  const ownerOptions = {
+    lockDir: transactionLockDir,
+    manifestPath,
+    environmentDir,
+    lockPath,
+    packages,
+    fileStat,
+    now: input.now ?? Date.now,
+    processAlive: input.processAlive ?? defaultProcessAlive,
+    retryDelay,
+    retryDelayMs: input.lockRetryDelayMs ?? 50,
+    attempts: input.lockAttempts ?? 100,
+    staleMs: input.lockStaleMs ?? 30_000,
+    renamePath,
+    removePath,
+  }
+
+  await mkdir(runDir, { recursive: true })
+  const hasRuntime = Boolean(input.capabilities.tools?.uv?.status === 'candidate' || input.capabilities.tools?.python?.status === 'candidate')
+  if (await exists(manifestPath, fileStat)) {
+    const existing = await inspectExisting({ environmentDir, manifestPath, lockPath, packages, fileStat })
+    if (existing?.status === 'ready' || !hasRuntime) return existing
+  }
+  const { owner, reclaimedDeadOwner } = await acquireLock(ownerOptions)
+  let committed = false
+  try {
+    if (reclaimedDeadOwner && await exists(environmentDir, fileStat) && !await exists(manifestPath, fileStat)) {
+      await removePath(environmentDir, { recursive: true, force: true })
+      await removePath(lockPath, { force: true }).catch(() => {})
+    }
+    const existing = await inspectExisting({ environmentDir, manifestPath, lockPath, packages, fileStat })
+    if (existing?.status === 'ready') return existing
+
+    const uv = await validateExecutable(input.capabilities.tools?.uv, 'uv', platform, fileStat)
+    const python = await validateExecutable(input.capabilities.tools?.python, 'python', platform, fileStat)
+    if (existing?.status === 'blocked') {
+      if (!uv && !python) return existing
+      await removePath(manifestPath, { force: true })
+    }
+    const commands = []
+    if (!uv && !python) {
+      const manifest = {
+        schemaVersion: 1, status: 'blocked', adapter: null, environmentDir, python: null,
+        requestedPackages: packages, lockPath: null, commands,
+        reason: 'No uv or Python runtime candidate is available.',
+      }
+      await atomicWriteJson(manifestPath, manifest)
+      return manifest
+    }
+
+    const attemptId = randomUUID()
+    const stagedLockPath = ensureContained(runDir, resolvePath(runDir, `requirements.lock.${attemptId}.tmp`), platform)
+    const stagedManifestPath = ensureContained(runDir, resolvePath(runDir, `python-environment.json.${attemptId}.tmp`), platform)
+    const finalPythonPath = environmentPython(environmentDir, platform, resolvePath)
+    try {
+      let adapter
+      if (uv) {
+        adapter = 'uv'
+        const createArgs = ['venv', '--seed', environmentDir]
+        commands.push({ command: uv.executable, args: createArgs })
+        assertSuccess(await runCommand(uv.executable, createArgs, { cwd: runDir }), 'uv venv')
+        if (packages.length) {
+          const installArgs = ['pip', 'install', '--python', finalPythonPath, ...packages]
+          commands.push({ command: uv.executable, args: installArgs })
+          assertSuccess(await runCommand(uv.executable, installArgs, { cwd: runDir }), 'uv pip install')
+        }
+      } else {
+        adapter = 'venv'
+        const createArgs = pythonVenvArgs(python, environmentDir, platform)
+        commands.push({ command: python.executable, args: createArgs })
+        assertSuccess(await runCommand(python.executable, createArgs, { cwd: runDir }), 'python venv')
+        if (packages.length) {
+          const installArgs = ['-m', 'pip', 'install', ...packages]
+          commands.push({ command: finalPythonPath, args: installArgs })
+          assertSuccess(await runCommand(finalPythonPath, installArgs, { cwd: runDir }), 'pip install')
+        }
+      }
+      await mkdir(environmentDir, { recursive: true })
+      await freezeRequirements(runCommand, finalPythonPath, finalPythonPath, runDir, stagedLockPath, lockPath, commands)
+      const manifest = {
+        schemaVersion: 1, status: 'ready', adapter, environmentDir, python: finalPythonPath,
+        requestedPackages: packages, lockPath, commands,
+      }
+      await writeFile(stagedManifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+      await renamePath(stagedLockPath, lockPath)
+      await renamePath(stagedManifestPath, manifestPath)
+      committed = true
+      return manifest
+    } catch (error) {
+      committed = await exists(manifestPath, fileStat)
+      if (!committed) {
+        await removePath(stagedLockPath, { force: true }).catch(() => {})
+        await removePath(stagedManifestPath, { force: true }).catch(() => {})
+        await removePath(lockPath, { force: true }).catch(() => {})
+        await removePath(environmentDir, { recursive: true, force: true }).catch(() => {})
+      }
+      throw error
+    }
+  } finally {
+    const release = releaseLock(transactionLockDir, owner, removePath)
+    if (committed) await release.catch(() => {})
+    else await release
+  }
+}
+
+export function parseArguments(argv) {
+  const result = { packages: [] }
+  const nextValue = (index, option) => {
+    const value = argv[index + 1]
+    if (value === undefined || value.startsWith('--')) throw new Error(`missing value for ${option}`)
+    return value
+  }
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]
+    if (value === '--run-dir') result.runDir = nextValue(index++, value)
+    else if (value === '--capabilities') result.capabilitiesPath = nextValue(index++, value)
+    else if (value === '--package') result.packages.push(nextValue(index++, value))
+    else throw new Error(`unknown argument: ${value}`)
+  }
+  if (!result.runDir || !result.capabilitiesPath) {
+    throw new Error('usage: python-environment.mjs --run-dir <path> --capabilities <json> [--package <spec>]')
+  }
+  return result
+}
+
+async function main() {
+  const args = parseArguments(process.argv.slice(2))
+  const capabilities = JSON.parse(await readFile(args.capabilitiesPath, 'utf8'))
+  const manifest = await createPythonEnvironment({ runDir: args.runDir, packages: args.packages, capabilities })
+  process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`)
+  if (manifest.status === 'blocked') process.exitCode = 2
+}
+
+const invokedPath = process.argv[1]
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = 1
+  })
+}