@foundation0/api 1.1.12 → 1.1.13

package/agents.ts

@@ -1,918 +1,918 @@
-import fs from 'fs'
-import path from 'path'
-import { spawnSync } from 'child_process'
-import { pathToFileURL } from 'url'
-
-export interface VersionedFileSpec {
-  parts: string[]
-  base: string
-  version: string | null
-  ext: string | null
-}
-
-export interface ActiveFileResult {
-  agentName: string
-  sourceFile: string
-  activeFile: string
-  matchedFile: string
-  mode: 'symlink'
-}
-
-export interface AgentLoadResult {
-  agentName: string
-  loaded: unknown
-}
-
-export interface AgentRunResult {
-  agentName: string
-  exitCode: number
-}
-
-export interface AgentCreateResult {
-  agentName: string
-  agentRoot: string
-  createdPaths: string[]
-}
-
-interface ActiveConfigInput {
-  path: string
-  required: boolean
-}
-
-const CLI_NAME = 'f0'
-const AGENT_INITIAL_VERSION = 'v0.0.1'
-const DEFAULT_SKILL_NAME = 'coding-standards'
-const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
-const VERSION_RE_CORE = `(?:${VERSION_RE})`
-const VERSION_WITH_EXT_RE = new RegExp(`^(.+)\\.(${VERSION_RE})\\.([A-Za-z][A-Za-z0-9_-]*)$`)
-const VERSION_ONLY_RE = new RegExp(`^(.+)\\.(${VERSION_RE})$`)
-const PRIORITIZED_EXTS = ['.md', '.json', '.yaml', '.yml', '.ts', '.js', '.txt']
-
-export function usage(): string {
-  return `Usage:\n  ${CLI_NAME} agents create <agent-name>\n  ${CLI_NAME} agents <agent-name> <file-path> --set-active\n  ${CLI_NAME} agents --list\n  ${CLI_NAME} agents <agent-name> load\n  ${CLI_NAME} agents <agent-name> run [codex-args...]\n\n` +
-    `Examples:\n  ${CLI_NAME} agents create reviewer\n  ${CLI_NAME} agents coder /system/boot.v0.0.1 --set-active\n  ${CLI_NAME} agents coder /system/boot --set-active --latest\n  ${CLI_NAME} agents coder /skills/coding-standards.v0.0.1 --set-active\n  ${CLI_NAME} agents --list\n` +
-    `  ${CLI_NAME} agents coder load\n` +
-    `  ${CLI_NAME} agents coder run --model gpt-5\n` +
-    `\n` +
-    `file-path is relative to the agent root (leading slash required).\n` +
-    `Use --latest to resolve /file-name to the latest version.\n` +
-    `The active file created is [file].active.<ext>.\n` +
-    `Use "run" to start codex with developer_instructions from system/prompt.ts.\n` +
-    `Set F0_CODEX_BIN (or EXAMPLE_CODEX_BIN) to pin a specific codex binary.\n`
-}
-
-export function resolveAgentsRoot(processRoot: string = process.cwd()): string {
-  const candidates = [
-    path.join(processRoot, 'agents'),
-    path.join(processRoot, 'wireborn', 'agents'),
-  ]
-
-  for (const candidatesPath of candidates) {
-    if (existsDir(candidatesPath)) {
-      return candidatesPath
-    }
-  }
-
-  const checked = candidates.map((candidate) => `\n  checked path: ${candidate}`).join('')
-
-  throw new Error(
-    `Could not find agents directory relative to working directory.\n  cwd: ${processRoot}${checked}`
-  )
-}
-
-export const resolveAgentsRootFrom = resolveAgentsRoot
-
-export function listAgents(processRoot: string = process.cwd()): string[] {
-  const agentsPath = resolveAgentsRoot(processRoot)
-
-  return fs
-    .readdirSync(agentsPath, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort((a, b) => a.localeCompare(b))
-}
-
-function normalizeAgentName(agentName: string): string {
-  if (!agentName || typeof agentName !== 'string') {
-    throw new Error('agent-name is required.')
-  }
-
-  const normalized = agentName.trim()
-  if (!normalized) {
-    throw new Error('agent-name is required.')
-  }
-
-  if (normalized.startsWith('-')) {
-    throw new Error(`Invalid agent-name: ${agentName}`)
-  }
-
-  if (normalized === '.' || normalized === '..' || normalized.includes('/') || normalized.includes('\\')) {
-    throw new Error(`Invalid agent-name: ${agentName}`)
-  }
-
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) {
-    throw new Error(`Invalid agent-name: ${agentName}`)
-  }
-
-  return normalized
-}
-
-function titleCaseAgentName(agentName: string): string {
-  return agentName
-    .split(/[-_]+/)
-    .filter(Boolean)
-    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
-    .join(' ')
-}
-
-function buildBootDocument(agentName: string): string {
-  const title = titleCaseAgentName(agentName) || agentName
-  return `# ${title} Agent Boot (${AGENT_INITIAL_VERSION})
-
-You are the \`${agentName}\` agent.
-
-## Role
-- Follow the active workflow and execute scoped tasks.
-- Keep outputs concise, concrete, and implementation-focused.
-- Avoid changing unrelated files or behavior.
-
-## Startup Sequence
-1. Read active boot/workflow docs and enabled skills.
-2. Confirm scope and constraints before changes.
-3. Apply the smallest safe change set.
-4. Report changed files and outcomes.
-`
-}
-
-function buildWorkflowDocument(agentName: string): string {
-  return `# ${titleCaseAgentName(agentName) || agentName} Workflow (${AGENT_INITIAL_VERSION})
-
-1. Parse request and constraints.
-2. Identify exact files and minimal edits.
-3. Implement and verify changes.
-4. If blocked, stop and report the blocker.
-5. Return result summary with next actions if needed.
-`
-}
-
-function buildToolsConfig(): string {
-  return `${JSON.stringify({
-    tools: [
-      {
-        name: 'shell_command',
-        enabled: true,
-        description: 'Execute shell commands for file and workspace operations.',
-      },
-      {
-        name: 'apply_patch',
-        enabled: true,
-        description: 'Apply focused file edits safely.',
-      },
-      {
-        name: 'read_file',
-        enabled: true,
-        description: 'Read files when needed for context.',
-      },
-    ],
-    permissions: {
-      network: false,
-      write: true,
-      delete: true,
-    },
-  }, null, 2)}
-`
-}
-
-function buildModelConfig(): string {
-  return `${JSON.stringify({
-    provider: 'openai',
-    model: 'gpt-5',
-    temperature: 0.2,
-    max_tokens: 4096,
-    top_p: 0.95,
-  }, null, 2)}
-`
-}
-
-function buildDefaultSkillDocument(): string {
-  return `# Coding Standards (${AGENT_INITIAL_VERSION})
-
-- Keep changes minimal and focused on the request.
-- Preserve existing behavior unless explicitly changing it.
-- Prefer readable, deterministic implementations.
-`
-}
-
-const SYSTEM_PROMPT_TS_TEMPLATE = `import * as fs from 'fs'
-import * as path from 'path'
-
-const base = path.join(__dirname)
-const readActive = (p: string) => fs.readFileSync(path.join(base, p), 'utf8')
-
-export const boot = readActive('boot.active.md')
-export const workflow = readActive('workflow.active.md')
-export const tools = JSON.parse(readActive('tools.active.json'))
-export const model = JSON.parse(readActive('model.active.json'))
-
-export const prompt = [boot, workflow].join('\\n\\n')
-
-export const agentConfig = {
-  boot,
-  workflow,
-  tools,
-  model,
-  prompt,
-}
-`
-
-const SKILLS_TS_TEMPLATE = `import * as fs from 'fs'
-import * as path from 'path'
-
-export interface SkillFile {
-  id: string
-  version: string
-  activeFile: string
-  resolvedFile: string
-  content: string
-}
-
-const skillsDir = path.join(__dirname)
-const enabledListPath = path.join(skillsDir, 'enabled-skills.md')
-
-const resolveVersionAndId = (activeFile: string) => {
-  const baseName = path.basename(activeFile, '.active.md')
-  const resolved = \`\${baseName}.${AGENT_INITIAL_VERSION}.md\`
-  return {
-    id: baseName,
-    version: '${AGENT_INITIAL_VERSION}',
-    resolvedFile: resolved,
-  }
-}
-
-const enabledLines = fs
-  .readFileSync(enabledListPath, 'utf8')
-  .split(/\\r?\\n/)
-  .map((line) => line.trim())
-  .filter(Boolean)
-
-export const skills: SkillFile[] = enabledLines.map((activeFile) => {
-  const resolved = resolveVersionAndId(activeFile)
-  return {
-    ...resolved,
-    activeFile,
-    content: fs.readFileSync(path.join(skillsDir, resolved.resolvedFile), 'utf8'),
-  }
-})
-`
-
-const LOAD_TS_TEMPLATE = `import { readFileSync } from 'fs'
-import * as path from 'path'
-
-import { agentConfig } from './system/prompt'
-import { skills } from './skills/skills'
-
-const activeDoc = path.join(__dirname, 'system')
-
-const loadActive = (name: string) =>
-  readFileSync(path.join(activeDoc, name), 'utf8').trim()
-
-export const load = () => ({
-  ...agentConfig,
-  bootDoc: loadActive('boot.active.md'),
-  workflowDoc: loadActive('workflow.active.md'),
-  skills,
-})
-
-export type AgentBundle = ReturnType<typeof load>
-`
-
-export function parseTargetSpec(spec: string): VersionedFileSpec {
-  if (!spec || typeof spec !== 'string') {
-    throw new Error('file-path is required.')
-  }
-
-  const normalized = spec.replace(/\\/g, '/').trim()
-
-  if (!normalized.startsWith('/')) {
-    throw new Error('file-path must start with a leading slash, e.g. /system/boot.v0.0.1')
-  }
-
-  const body = normalized.slice(1)
-  if (!body) {
-    throw new Error('file-path is empty.')
-  }
-
-  const parts = body.split('/').filter(Boolean)
-  if (parts.length < 2) {
-    throw new Error('file-path must include a file name, for example /system/boot.v0.0.1')
-  }
-
-  const file = parts.pop()
-  if (!file) {
-    throw new Error('file-path must include a file name, for example /system/boot.v0.0.1')
-  }
-
-  const withExt = file.match(VERSION_WITH_EXT_RE)
-  const withoutExt = file.match(VERSION_ONLY_RE)
-  if (withExt) {
-    return {
-      parts,
-      base: withExt[1],
-      version: withExt[2],
-      ext: withExt[3],
-    }
-  }
-
-  if (withoutExt) {
-    return {
-      parts,
-      base: withoutExt[1],
-      version: withoutExt[2],
-      ext: null,
-    }
-  }
-
-  if (parts.length === 0) {
-    throw new Error('file-path must include a file name, for example /system/boot or /system/boot.v0.0.1.')
-  }
-
-  return {
-    parts,
-    base: file,
-    version: null,
-    ext: null,
-  }
-}
-
-function parseVersion(version: string): number[] {
-  const clean = version.replace(/^v/, '')
-  return clean.split('.').filter(Boolean).map((part) => Number.parseInt(part, 10))
-}
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-function compareVersions(left: string, right: string): number {
-  const a = parseVersion(left)
-  const b = parseVersion(right)
-  const size = Math.max(a.length, b.length)
-
-  for (let i = 0; i < size; i += 1) {
-    const leftValue = a[i] ?? 0
-    const rightValue = b[i] ?? 0
-    if (leftValue > rightValue) return 1
-    if (leftValue < rightValue) return -1
-  }
-
-  return 0
-}
-
-function findLatestVersionedFile(targetDir: string, base: string, ext: string | null): string | null {
-  const fileEntries = fs
-    .readdirSync(targetDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile())
-    .map((entry) => entry.name)
-
-  const safeBase = escapeRegExp(base)
-  const regex = new RegExp(`^${safeBase}\\.(${VERSION_RE_CORE})\\.([^.]+)$`)
-  const matches = fileEntries
-    .map((entry) => {
-      const match = entry.match(regex)
-      if (!match) return null
-
-      const version = match[1]
-      const detectedExt = `.${match[2]}`
-      if (ext && detectedExt !== `.${ext}`) {
-        return null
-      }
-
-      return { entry, version, detectedExt }
-    })
-    .filter((value): value is { entry: string; version: string; detectedExt: string } => value !== null)
-
-  if (matches.length === 0) return null
-
-  matches.sort((a, b) => compareVersions(a.version, b.version))
-  const selected = matches[matches.length - 1]
-
-  const version = selected.version
-  const sameVersion = matches
-    .filter((item) => compareVersions(item.version, version) === 0)
-    .map((item) => item.entry)
-    .sort()
-
-  if (sameVersion.length <= 1) {
-    return sameVersion[0]
-  }
-
-  for (const extName of PRIORITIZED_EXTS) {
-    const preferred = sameVersion.find((entryName) => entryName.endsWith(extName))
-    if (preferred) {
-      return preferred
-    }
-  }
-
-  return sameVersion.sort()[0]
-}
-
-export function resolveTargetFile(targetDir: string, spec: VersionedFileSpec, options: { latest?: boolean } = {}): string | null {
-  const entries = fs
-    .readdirSync(targetDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile())
-    .map((entry) => entry.name)
-
-  if (!spec.version) {
-    if (!options.latest) {
-      return null
-    }
-    return findLatestVersionedFile(targetDir, spec.base, null)
-  }
-
-  if (spec.ext) {
-    const exact = `${spec.base}.${spec.version}.${spec.ext}`
-    if (entries.includes(exact)) {
-      return exact
-    }
-    return null
-  }
-
-  const prefix = `${spec.base}.${spec.version}.`
-  const candidates = entries.filter((entry) => entry.startsWith(prefix))
-  if (candidates.length === 0) {
-    return null
-  }
-
-  for (const ext of PRIORITIZED_EXTS) {
-    const match = candidates.find((entry) => entry.endsWith(ext))
-    if (match) {
-      return match
-    }
-  }
-
-  return candidates.sort()[0]
-}
-
-export function setActiveLink(sourceFile: string, activeFile: string): 'symlink' {
-  if (!existsFile(sourceFile)) {
-    throw new Error(`Versioned file not found: ${sourceFile}`)
-  }
-
-  fs.mkdirSync(path.dirname(activeFile), { recursive: true })
-
-  // Remove the active pointer first. Using rmSync directly (instead of existsSync)
-  // ensures we also clear broken symlinks (existsSync returns false for them).
-  fs.rmSync(activeFile, { force: true })
-
-  const linkTarget = path.relative(path.dirname(activeFile), sourceFile)
-
-  try {
-    fs.symlinkSync(linkTarget, activeFile, 'file')
-    return 'symlink'
-  } catch (error) {
-    if (process.platform === 'win32') {
-      const ok = createWindowsSymlink(activeFile, sourceFile)
-      if (ok) {
-        return 'symlink'
-      }
-      throw new Error(
-        `Failed to create symlink on Windows. Run shell as Administrator or enable Developer Mode.\n${String(error?.message ?? error)}`
-      )
-    }
-
-    throw error
-  }
-}
-
-function createWindowsSymlink(activeFile: string, sourceFile: string): boolean {
-  const quote = (value: string) => `"${value.replace(/\"/g, '""')}"`
-  const command = `mklink ${quote(path.resolve(activeFile))} ${quote(path.resolve(sourceFile))}`
-  const result = spawnSync('cmd', ['/c', command], {
-    shell: false,
-    encoding: 'utf8',
-  })
-
-  return result.status === 0
-}
-
-export function createAgent(agentName: string, processRoot: string = process.cwd()): AgentCreateResult {
-  const normalizedAgentName = normalizeAgentName(agentName)
-  const agentsRoot = resolveAgentsRootFrom(processRoot)
-  const agentRoot = path.join(agentsRoot, normalizedAgentName)
-
-  if (fs.existsSync(agentRoot)) {
-    throw new Error(`Agent folder already exists: ${agentRoot}`)
-  }
-
-  const systemDir = path.join(agentRoot, 'system')
-  const skillsDir = path.join(agentRoot, 'skills')
-
-  fs.mkdirSync(systemDir, { recursive: true })
-  fs.mkdirSync(skillsDir, { recursive: true })
-
-  const createdPaths: string[] = []
-  const writeFile = (relativePath: string, content: string) => {
-    const absolutePath = path.join(agentRoot, relativePath)
-    fs.mkdirSync(path.dirname(absolutePath), { recursive: true })
-    fs.writeFileSync(absolutePath, content, 'utf8')
-    createdPaths.push(absolutePath)
-  }
-
-  const bootFileName = `boot.${AGENT_INITIAL_VERSION}.md`
-  const workflowFileName = `workflow.${AGENT_INITIAL_VERSION}.md`
-  const toolsFileName = `tools.${AGENT_INITIAL_VERSION}.json`
-  const modelFileName = `model.${AGENT_INITIAL_VERSION}.json`
-  const skillFileName = `${DEFAULT_SKILL_NAME}.${AGENT_INITIAL_VERSION}.md`
-  const activeSkillFileName = `${DEFAULT_SKILL_NAME}.active.md`
-
-  writeFile(path.join('system', bootFileName), buildBootDocument(normalizedAgentName))
-  writeFile(path.join('system', workflowFileName), buildWorkflowDocument(normalizedAgentName))
-  writeFile(path.join('system', toolsFileName), buildToolsConfig())
-  writeFile(path.join('system', modelFileName), buildModelConfig())
-  writeFile(path.join('system', 'prompt.ts'), SYSTEM_PROMPT_TS_TEMPLATE)
-
-  writeFile(path.join('skills', skillFileName), buildDefaultSkillDocument())
-  writeFile(path.join('skills', 'enabled-skills.md'), `${activeSkillFileName}\n`)
-  writeFile(path.join('skills', 'skills.ts'), SKILLS_TS_TEMPLATE)
-
-  writeFile('load.ts', LOAD_TS_TEMPLATE)
-
-  const createActiveLink = (versionedFile: string, activeFile: string) => {
-    const source = path.join(agentRoot, versionedFile)
-    const target = path.join(agentRoot, activeFile)
-    setActiveLink(source, target)
-    createdPaths.push(target)
-  }
-
-  createActiveLink(path.join('system', bootFileName), path.join('system', 'boot.active.md'))
-  createActiveLink(path.join('system', workflowFileName), path.join('system', 'workflow.active.md'))
-  createActiveLink(path.join('system', toolsFileName), path.join('system', 'tools.active.json'))
-  createActiveLink(path.join('system', modelFileName), path.join('system', 'model.active.json'))
-  createActiveLink(path.join('skills', skillFileName), path.join('skills', activeSkillFileName))
-
-  return {
-    agentName: normalizedAgentName,
-    agentRoot,
-    createdPaths: createdPaths.sort((a, b) => a.localeCompare(b)),
-  }
-}
-
-export function setActive(
-  agentName: string,
-  target: string,
-  processRoot: string = process.cwd(),
-  options: { latest?: boolean } = {}
-): ActiveFileResult {
-  const spec = parseTargetSpec(target)
-  const agentsRoot = resolveAgentsRootFrom(processRoot)
-  const targetDir = path.join(agentsRoot, agentName, ...spec.parts)
-  const agentDir = path.join(agentsRoot, agentName)
-
-  if (!existsDir(agentDir)) {
-    throw new Error(`Agent folder not found: ${agentDir}`)
-  }
-
-  if (!existsDir(targetDir)) {
-    throw new Error(`Target folder not found: ${targetDir}`)
-  }
-
-  const matchedFile = resolveTargetFile(targetDir, spec, options)
-  if (!matchedFile && !spec.version && options.latest) {
-    throw new Error(`No files found for /${spec.parts.join('/')}${spec.parts.length > 0 ? '/' : ''}${spec.base}`)
-  }
-  if (!matchedFile) {
-    if (!spec.version && !options.latest) {
-      throw new Error(
-        `Version missing for /${spec.parts.join('/')}/${spec.base}. Use --latest to select the latest version.`
-      )
-    }
-    const extensionHint = spec.ext ? `.${spec.ext}` : ' with any extension'
-    throw new Error(
-      `Versioned file not found for /${spec.parts.join('/')}/${spec.base}.${spec.version}${extensionHint}`
-    )
-  }
-
-  const sourceFile = path.join(targetDir, matchedFile)
-  const activeFile = path.join(targetDir, `${spec.base}.active${path.extname(matchedFile)}`)
-  const mode = setActiveLink(sourceFile, activeFile)
-
-  return {
-    agentName,
-    sourceFile,
-    activeFile,
-    matchedFile,
-    mode,
-  }
-}
-
-export async function loadAgent(agentName: string, processRoot: string = process.cwd()): Promise<AgentLoadResult> {
-  const agentsRoot = resolveAgentsRoot(processRoot)
-  const agentDir = path.join(agentsRoot, agentName)
-
-  if (!existsDir(agentDir)) {
-    throw new Error(`Agent folder not found: ${agentDir}`)
-  }
-
-  const loadFile = path.join(agentDir, 'load.ts')
-  if (!existsFile(loadFile)) {
-    throw new Error(`Load file not found for agent '${agentName}': ${loadFile}`)
-  }
-
-  validateActiveConfigInputs(agentDir)
-
-  const moduleUrl = pathToFileURL(loadFile).href
-  const module = await import(moduleUrl)
-  const loadFn = module.load
-
-  if (typeof loadFn !== 'function') {
-    throw new Error(`Load module for agent '${agentName}' must export a 'load' function.`)
-  }
-
-  return {
-    agentName,
-    loaded: await loadFn(),
-  }
-}
-
-type SpawnCodexResult = {
-  status: number | null
-  signal: NodeJS.Signals | null
-  error?: Error
-}
-
-type SpawnCodexFn = (args: string[]) => SpawnCodexResult
-
-function getCodexCommand(): string {
-  const override = process.env.F0_CODEX_BIN?.trim() ?? process.env.EXAMPLE_CODEX_BIN?.trim()
-  if (override) {
-    return override
-  }
-  if (process.platform === 'win32') {
-    // Prefer npm/pnpm cmd shim over stale codex.exe binaries.
-    return 'codex.cmd'
-  }
-  return 'codex'
-}
-
-const defaultSpawnCodex: SpawnCodexFn = (args) => {
-  const spawnOptions = {
-    stdio: 'inherit' as const,
-    env: process.env,
-  }
-
-  const primaryCommand = getCodexCommand()
-  const primary = spawnSync(primaryCommand, args, spawnOptions)
-  if (primary.error) {
-    const err = primary.error as NodeJS.ErrnoException
-    if (
-      process.platform === 'win32'
-      && !process.env.F0_CODEX_BIN
-      && !process.env.EXAMPLE_CODEX_BIN
-      && primaryCommand === 'codex.cmd'
-      && err.code === 'ENOENT'
-    ) {
-      return spawnSync('codex', args, spawnOptions)
-    }
-  }
-
-  return primary
-}
-
-function toExitCode(signal: NodeJS.Signals | null): number {
-  if (!signal) {
-    return 1
-  }
-  if (signal === 'SIGINT') {
-    return 130
-  }
-  if (signal === 'SIGTERM') {
-    return 143
-  }
-  return 1
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
-async function resolvePromptValue(value: unknown): Promise<unknown> {
-  if (typeof value === 'function') {
-    return await value()
-  }
-  return value
-}
-
-function extractPromptString(value: unknown): string | null {
-  if (typeof value === 'string') {
-    return value
-  }
-  if (isRecord(value) && typeof value.prompt === 'string') {
-    return value.prompt
-  }
-  return null
-}
-
-export async function loadAgentPrompt(agentName: string, processRoot: string = process.cwd()): Promise<string> {
-  const agentsRoot = resolveAgentsRoot(processRoot)
-  const agentDir = path.join(agentsRoot, agentName)
-
-  if (!existsDir(agentDir)) {
-    throw new Error(`Agent folder not found: ${agentDir}`)
-  }
-
-  const promptFile = path.join(agentDir, 'system', 'prompt.ts')
-  if (!existsFile(promptFile)) {
-    throw new Error(`Prompt file not found for agent '${agentName}': ${promptFile}`)
-  }
-
-  const promptModuleUrl = pathToFileURL(promptFile).href
-  const promptModule = await import(promptModuleUrl)
-  const candidates = [
-    await resolvePromptValue(promptModule.prompt),
-    await resolvePromptValue(promptModule.agentConfig),
-    await resolvePromptValue(promptModule.default),
-  ]
-
-  for (const candidate of candidates) {
-    const promptText = extractPromptString(candidate)
-    if (promptText !== null) {
-      return promptText
-    }
-  }
-
-  throw new Error(`Prompt module for agent '${agentName}' must export a prompt string.`)
-}
-
-export async function runAgent(
-  agentName: string,
-  codexArgs: string[] = [],
-  processRoot: string = process.cwd(),
-  options: { spawnCodex?: SpawnCodexFn } = {}
-): Promise<AgentRunResult> {
-  const prompt = await loadAgentPrompt(agentName, processRoot)
-  const spawnCodex = options.spawnCodex ?? defaultSpawnCodex
-  const args = ['--config', `developer_instructions=${prompt}`, ...codexArgs]
-  const result = spawnCodex(args)
-
-  if (result.error) {
-    throw new Error(`Failed to start codex: ${result.error.message}`)
-  }
-
-  return {
-    agentName,
-    exitCode: typeof result.status === 'number' ? result.status : toExitCode(result.signal),
-  }
-}
-
-function validateActiveConfigInputs(agentDir: string): void {
-  const issues: string[] = []
-
-  const requiredInputs = collectActiveConfigInputs(agentDir)
-
-  for (const input of requiredInputs) {
-    if (!existsFile(input.path)) {
-      if (input.required) {
-        issues.push(`missing: ${path.relative(agentDir, input.path)}`)
-      }
-      continue
-    }
-
-    if (!isSymbolicLink(input.path)) {
-      issues.push(`not a symlink: ${path.relative(agentDir, input.path)}`)
-    }
-  }
-
-  if (issues.length > 0) {
-    throw new Error(`Config input check failed: ${issues.join(', ')}`)
-  }
-}
-
-function collectActiveConfigInputs(agentDir: string): ActiveConfigInput[] {
-  const systemDir = path.join(agentDir, 'system')
-  const skillsDir = path.join(agentDir, 'skills')
-
-  const required: ActiveConfigInput[] = [
-    { path: path.join(systemDir, 'boot.active.md'), required: true },
-    { path: path.join(systemDir, 'workflow.active.md'), required: true },
-    { path: path.join(systemDir, 'tools.active.json'), required: true },
-    { path: path.join(systemDir, 'model.active.json'), required: true },
-  ]
-
-  const enabledSkillsPath = path.join(skillsDir, 'enabled-skills.md')
-  if (!existsFile(enabledSkillsPath)) {
-    return required
-  }
-
-  const lines = fs.readFileSync(enabledSkillsPath, 'utf8')
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean)
-
-  for (const line of lines) {
-    required.push({ path: path.join(skillsDir, line), required: true })
-  }
-
-  return required
-}
-
-function isSymbolicLink(filePath: string): boolean {
-  try {
-    return fs.lstatSync(filePath).isSymbolicLink()
-  } catch {
-    return false
-  }
-}
-
-export async function main(argv: string[], processRoot: string = process.cwd()): Promise<string> {
-  if (
-    argv.length === 0 ||
-    argv.includes('--help') ||
-    argv.includes('-h')
-  ) {
-    return usage()
-  }
-
-  const [scope, maybeAgentOrFlag, maybeTarget, ...rest] = argv
-  const listMode = scope === 'agents' && maybeAgentOrFlag === '--list'
-  const createMode = scope === 'agents' && maybeAgentOrFlag === 'create'
-
-  if (scope !== 'agents') {
-    throw new Error('Expected command `agents` as first positional argument.')
-  }
-
-  if (listMode) {
-    const unknownFlags = rest.filter(Boolean)
-    if (unknownFlags.length > 0) {
-      throw new Error(`Unknown flags for list mode: ${unknownFlags.join(', ')}`)
-    }
-    return listAgents(processRoot).join('\n')
-  }
-
-  if (createMode) {
-    if (!maybeTarget) {
-      throw new Error('Missing required argument: <agent-name>.')
-    }
-
-    const unknownFlags = rest.filter(Boolean)
-    if (unknownFlags.length > 0) {
-      throw new Error(`Unknown flags for create mode: ${unknownFlags.join(', ')}`)
-    }
-
-    const result = createAgent(maybeTarget, processRoot)
-    const displayPath = path.relative(processRoot, result.agentRoot) || result.agentRoot
-    return `[${CLI_NAME}] created agent: ${result.agentName} (${displayPath})`
-  }
-
-  const agentName = maybeAgentOrFlag
-  const target = maybeTarget
-  const setActiveRequested = rest.includes('--set-active')
-  const useLatest = rest.includes('--latest')
-
-  if (target === 'load') {
-    if (rest.length > 0) {
-      throw new Error(`Unknown flags for load mode: ${rest.join(', ')}`)
-    }
-    const result = await loadAgent(agentName, processRoot)
-    return JSON.stringify(result.loaded, null, 2)
-  }
-
-  if (target === 'run') {
-    const result = await runAgent(agentName, rest, processRoot)
-    if (result.exitCode !== 0) {
-      process.exitCode = result.exitCode
-    }
-    return ''
-  }
-
-  if (!agentName || !target) {
-    throw new Error('Missing required arguments: <agent-name> and <file-path>.')
-  }
-
-  if (!setActiveRequested) {
-    throw new Error('`--set-active` is required for this operation.')
-  }
-
-  const unknownFlags = rest.filter((arg) => arg !== '--set-active' && arg !== '--latest')
-  if (unknownFlags.length > 0) {
-    throw new Error(`Unknown flags: ${unknownFlags.join(', ')}`)
-  }
-
-  const result = setActive(agentName, target, processRoot, { latest: useLatest })
-  return `[${CLI_NAME}] set active: ${result.matchedFile} -> ${path.basename(result.activeFile)} (${result.mode})`
-}
-
-function existsDir(p: string): boolean {
-  try {
-    return fs.statSync(p).isDirectory()
-  } catch {
-    return false
-  }
-}
-
-function existsFile(p: string): boolean {
-  try {
-    return fs.statSync(p).isFile()
-  } catch {
-    return false
-  }
-}
+import fs from 'fs'
+import path from 'path'
+import { spawnSync } from 'child_process'
+import { pathToFileURL } from 'url'
+
+export interface VersionedFileSpec {
+  parts: string[]
+  base: string
+  version: string | null
+  ext: string | null
+}
+
+export interface ActiveFileResult {
+  agentName: string
+  sourceFile: string
+  activeFile: string
+  matchedFile: string
+  mode: 'symlink'
+}
+
+export interface AgentLoadResult {
+  agentName: string
+  loaded: unknown
+}
+
+export interface AgentRunResult {
+  agentName: string
+  exitCode: number
+}
+
+export interface AgentCreateResult {
+  agentName: string
+  agentRoot: string
+  createdPaths: string[]
+}
+
+interface ActiveConfigInput {
+  path: string
+  required: boolean
+}
+
+const CLI_NAME = 'f0'
+const AGENT_INITIAL_VERSION = 'v0.0.1'
+const DEFAULT_SKILL_NAME = 'coding-standards'
+const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
+const VERSION_RE_CORE = `(?:${VERSION_RE})`
+const VERSION_WITH_EXT_RE = new RegExp(`^(.+)\\.(${VERSION_RE})\\.([A-Za-z][A-Za-z0-9_-]*)$`)
+const VERSION_ONLY_RE = new RegExp(`^(.+)\\.(${VERSION_RE})$`)
+const PRIORITIZED_EXTS = ['.md', '.json', '.yaml', '.yml', '.ts', '.js', '.txt']
+
+export function usage(): string {
+  return `Usage:\n  ${CLI_NAME} agents create <agent-name>\n  ${CLI_NAME} agents <agent-name> <file-path> --set-active\n  ${CLI_NAME} agents --list\n  ${CLI_NAME} agents <agent-name> load\n  ${CLI_NAME} agents <agent-name> run [codex-args...]\n\n` +
+    `Examples:\n  ${CLI_NAME} agents create reviewer\n  ${CLI_NAME} agents coder /system/boot.v0.0.1 --set-active\n  ${CLI_NAME} agents coder /system/boot --set-active --latest\n  ${CLI_NAME} agents coder /skills/coding-standards.v0.0.1 --set-active\n  ${CLI_NAME} agents --list\n` +
+    `  ${CLI_NAME} agents coder load\n` +
+    `  ${CLI_NAME} agents coder run --model gpt-5\n` +
+    `\n` +
+    `file-path is relative to the agent root (leading slash required).\n` +
+    `Use --latest to resolve /file-name to the latest version.\n` +
+    `The active file created is [file].active.<ext>.\n` +
+    `Use "run" to start codex with developer_instructions from system/prompt.ts.\n` +
+    `Set F0_CODEX_BIN (or EXAMPLE_CODEX_BIN) to pin a specific codex binary.\n`
+}
+
+export function resolveAgentsRoot(processRoot: string = process.cwd()): string {
+  const candidates = [
+    path.join(processRoot, 'agents'),
+    path.join(processRoot, 'wireborn', 'agents'),
+  ]
+
+  for (const candidatesPath of candidates) {
+    if (existsDir(candidatesPath)) {
+      return candidatesPath
+    }
+  }
+
+  const checked = candidates.map((candidate) => `\n  checked path: ${candidate}`).join('')
+
+  throw new Error(
+    `Could not find agents directory relative to working directory.\n  cwd: ${processRoot}${checked}`
+  )
+}
+
+export const resolveAgentsRootFrom = resolveAgentsRoot
+
+export function listAgents(processRoot: string = process.cwd()): string[] {
+  const agentsPath = resolveAgentsRoot(processRoot)
+
+  return fs
+    .readdirSync(agentsPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b))
+}
+
+function normalizeAgentName(agentName: string): string {
+  if (!agentName || typeof agentName !== 'string') {
+    throw new Error('agent-name is required.')
+  }
+
+  const normalized = agentName.trim()
+  if (!normalized) {
+    throw new Error('agent-name is required.')
+  }
+
+  if (normalized.startsWith('-')) {
+    throw new Error(`Invalid agent-name: ${agentName}`)
+  }
+
+  if (normalized === '.' || normalized === '..' || normalized.includes('/') || normalized.includes('\\')) {
+    throw new Error(`Invalid agent-name: ${agentName}`)
+  }
+
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) {
+    throw new Error(`Invalid agent-name: ${agentName}`)
+  }
+
+  return normalized
+}
+
+function titleCaseAgentName(agentName: string): string {
+  return agentName
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join(' ')
+}
+
+function buildBootDocument(agentName: string): string {
+  const title = titleCaseAgentName(agentName) || agentName
+  return `# ${title} Agent Boot (${AGENT_INITIAL_VERSION})
+
+You are the \`${agentName}\` agent.
+
+## Role
+- Follow the active workflow and execute scoped tasks.
+- Keep outputs concise, concrete, and implementation-focused.
+- Avoid changing unrelated files or behavior.
+
+## Startup Sequence
+1. Read active boot/workflow docs and enabled skills.
+2. Confirm scope and constraints before changes.
+3. Apply the smallest safe change set.
+4. Report changed files and outcomes.
+`
+}
+
+function buildWorkflowDocument(agentName: string): string {
+  return `# ${titleCaseAgentName(agentName) || agentName} Workflow (${AGENT_INITIAL_VERSION})
+
+1. Parse request and constraints.
+2. Identify exact files and minimal edits.
+3. Implement and verify changes.
+4. If blocked, stop and report the blocker.
+5. Return result summary with next actions if needed.
+`
+}
+
+function buildToolsConfig(): string {
+  return `${JSON.stringify({
+    tools: [
+      {
+        name: 'shell_command',
+        enabled: true,
+        description: 'Execute shell commands for file and workspace operations.',
+      },
+      {
+        name: 'apply_patch',
+        enabled: true,
+        description: 'Apply focused file edits safely.',
+      },
+      {
+        name: 'read_file',
+        enabled: true,
+        description: 'Read files when needed for context.',
+      },
+    ],
+    permissions: {
+      network: false,
+      write: true,
+      delete: true,
+    },
+  }, null, 2)}
+`
+}
+
+function buildModelConfig(): string {
+  return `${JSON.stringify({
+    provider: 'openai',
+    model: 'gpt-5',
+    temperature: 0.2,
+    max_tokens: 4096,
+    top_p: 0.95,
+  }, null, 2)}
+`
+}
+
+function buildDefaultSkillDocument(): string {
+  return `# Coding Standards (${AGENT_INITIAL_VERSION})
+
+- Keep changes minimal and focused on the request.
+- Preserve existing behavior unless explicitly changing it.
+- Prefer readable, deterministic implementations.
+`
+}
+
+const SYSTEM_PROMPT_TS_TEMPLATE = `import * as fs from 'fs'
+import * as path from 'path'
+
+const base = path.join(__dirname)
+const readActive = (p: string) => fs.readFileSync(path.join(base, p), 'utf8')
+
+export const boot = readActive('boot.active.md')
+export const workflow = readActive('workflow.active.md')
+export const tools = JSON.parse(readActive('tools.active.json'))
+export const model = JSON.parse(readActive('model.active.json'))
+
+export const prompt = [boot, workflow].join('\\n\\n')
+
+export const agentConfig = {
+  boot,
+  workflow,
+  tools,
+  model,
+  prompt,
+}
+`
+
+const SKILLS_TS_TEMPLATE = `import * as fs from 'fs'
+import * as path from 'path'
+
+export interface SkillFile {
+  id: string
+  version: string
+  activeFile: string
+  resolvedFile: string
+  content: string
+}
+
+const skillsDir = path.join(__dirname)
+const enabledListPath = path.join(skillsDir, 'enabled-skills.md')
+
+const resolveVersionAndId = (activeFile: string) => {
+  const baseName = path.basename(activeFile, '.active.md')
+  const resolved = \`\${baseName}.${AGENT_INITIAL_VERSION}.md\`
+  return {
+    id: baseName,
+    version: '${AGENT_INITIAL_VERSION}',
+    resolvedFile: resolved,
+  }
+}
+
+const enabledLines = fs
+  .readFileSync(enabledListPath, 'utf8')
+  .split(/\\r?\\n/)
+  .map((line) => line.trim())
+  .filter(Boolean)
+
+export const skills: SkillFile[] = enabledLines.map((activeFile) => {
+  const resolved = resolveVersionAndId(activeFile)
+  return {
+    ...resolved,
+    activeFile,
+    content: fs.readFileSync(path.join(skillsDir, resolved.resolvedFile), 'utf8'),
+  }
+})
+`
+
+const LOAD_TS_TEMPLATE = `import { readFileSync } from 'fs'
+import * as path from 'path'
+
+import { agentConfig } from './system/prompt'
+import { skills } from './skills/skills'
+
+const activeDoc = path.join(__dirname, 'system')
+
+const loadActive = (name: string) =>
+  readFileSync(path.join(activeDoc, name), 'utf8').trim()
+
+export const load = () => ({
+  ...agentConfig,
+  bootDoc: loadActive('boot.active.md'),
+  workflowDoc: loadActive('workflow.active.md'),
+  skills,
+})
+
+export type AgentBundle = ReturnType<typeof load>
+`
+
+export function parseTargetSpec(spec: string): VersionedFileSpec {
+  if (!spec || typeof spec !== 'string') {
+    throw new Error('file-path is required.')
+  }
+
+  const normalized = spec.replace(/\\/g, '/').trim()
+
+  if (!normalized.startsWith('/')) {
+    throw new Error('file-path must start with a leading slash, e.g. /system/boot.v0.0.1')
+  }
+
+  const body = normalized.slice(1)
+  if (!body) {
+    throw new Error('file-path is empty.')
+  }
+
+  const parts = body.split('/').filter(Boolean)
+  if (parts.length < 2) {
+    throw new Error('file-path must include a file name, for example /system/boot.v0.0.1')
+  }
+
+  const file = parts.pop()
+  if (!file) {
+    throw new Error('file-path must include a file name, for example /system/boot.v0.0.1')
+  }
+
+  const withExt = file.match(VERSION_WITH_EXT_RE)
+  const withoutExt = file.match(VERSION_ONLY_RE)
+  if (withExt) {
+    return {
+      parts,
+      base: withExt[1],
+      version: withExt[2],
+      ext: withExt[3],
+    }
+  }
+
+  if (withoutExt) {
+    return {
+      parts,
+      base: withoutExt[1],
+      version: withoutExt[2],
+      ext: null,
+    }
+  }
+
+  if (parts.length === 0) {
+    throw new Error('file-path must include a file name, for example /system/boot or /system/boot.v0.0.1.')
+  }
+
+  return {
+    parts,
+    base: file,
+    version: null,
+    ext: null,
+  }
+}
+
+function parseVersion(version: string): number[] {
+  const clean = version.replace(/^v/, '')
+  return clean.split('.').filter(Boolean).map((part) => Number.parseInt(part, 10))
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function compareVersions(left: string, right: string): number {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  const size = Math.max(a.length, b.length)
+
+  for (let i = 0; i < size; i += 1) {
+    const leftValue = a[i] ?? 0
+    const rightValue = b[i] ?? 0
+    if (leftValue > rightValue) return 1
+    if (leftValue < rightValue) return -1
+  }
+
+  return 0
+}
+
+function findLatestVersionedFile(targetDir: string, base: string, ext: string | null): string | null {
+  const fileEntries = fs
+    .readdirSync(targetDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+
+  const safeBase = escapeRegExp(base)
+  const regex = new RegExp(`^${safeBase}\\.(${VERSION_RE_CORE})\\.([^.]+)$`)
+  const matches = fileEntries
+    .map((entry) => {
+      const match = entry.match(regex)
+      if (!match) return null
+
+      const version = match[1]
+      const detectedExt = `.${match[2]}`
+      if (ext && detectedExt !== `.${ext}`) {
+        return null
+      }
+
+      return { entry, version, detectedExt }
+    })
+    .filter((value): value is { entry: string; version: string; detectedExt: string } => value !== null)
+
+  if (matches.length === 0) return null
+
+  matches.sort((a, b) => compareVersions(a.version, b.version))
+  const selected = matches[matches.length - 1]
+
+  const version = selected.version
+  const sameVersion = matches
+    .filter((item) => compareVersions(item.version, version) === 0)
+    .map((item) => item.entry)
+    .sort()
+
+  if (sameVersion.length <= 1) {
+    return sameVersion[0]
+  }
+
+  for (const extName of PRIORITIZED_EXTS) {
+    const preferred = sameVersion.find((entryName) => entryName.endsWith(extName))
+    if (preferred) {
+      return preferred
+    }
+  }
+
+  return sameVersion.sort()[0]
+}
+
+export function resolveTargetFile(targetDir: string, spec: VersionedFileSpec, options: { latest?: boolean } = {}): string | null {
+  const entries = fs
+    .readdirSync(targetDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+
+  if (!spec.version) {
+    if (!options.latest) {
+      return null
+    }
+    return findLatestVersionedFile(targetDir, spec.base, null)
+  }
+
+  if (spec.ext) {
+    const exact = `${spec.base}.${spec.version}.${spec.ext}`
+    if (entries.includes(exact)) {
+      return exact
+    }
+    return null
+  }
+
+  const prefix = `${spec.base}.${spec.version}.`
+  const candidates = entries.filter((entry) => entry.startsWith(prefix))
+  if (candidates.length === 0) {
+    return null
+  }
+
+  for (const ext of PRIORITIZED_EXTS) {
+    const match = candidates.find((entry) => entry.endsWith(ext))
+    if (match) {
+      return match
+    }
+  }
+
+  return candidates.sort()[0]
+}
+
+export function setActiveLink(sourceFile: string, activeFile: string): 'symlink' {
+  if (!existsFile(sourceFile)) {
+    throw new Error(`Versioned file not found: ${sourceFile}`)
+  }
+
+  fs.mkdirSync(path.dirname(activeFile), { recursive: true })
+
+  // Remove the active pointer first. Using rmSync directly (instead of existsSync)
+  // ensures we also clear broken symlinks (existsSync returns false for them).
+  fs.rmSync(activeFile, { force: true })
+
+  const linkTarget = path.relative(path.dirname(activeFile), sourceFile)
+
+  try {
+    fs.symlinkSync(linkTarget, activeFile, 'file')
+    return 'symlink'
+  } catch (error) {
+    if (process.platform === 'win32') {
+      const ok = createWindowsSymlink(activeFile, sourceFile)
+      if (ok) {
+        return 'symlink'
+      }
+      throw new Error(
+        `Failed to create symlink on Windows. Run shell as Administrator or enable Developer Mode.\n${String(error?.message ?? error)}`
+      )
+    }
+
+    throw error
+  }
+}
+
+function createWindowsSymlink(activeFile: string, sourceFile: string): boolean {
+  const quote = (value: string) => `"${value.replace(/\"/g, '""')}"`
+  const command = `mklink ${quote(path.resolve(activeFile))} ${quote(path.resolve(sourceFile))}`
+  const result = spawnSync('cmd', ['/c', command], {
+    shell: false,
+    encoding: 'utf8',
+  })
+
+  return result.status === 0
+}
+
+export function createAgent(agentName: string, processRoot: string = process.cwd()): AgentCreateResult {
+  const normalizedAgentName = normalizeAgentName(agentName)
+  const agentsRoot = resolveAgentsRootFrom(processRoot)
+  const agentRoot = path.join(agentsRoot, normalizedAgentName)
+
+  if (fs.existsSync(agentRoot)) {
+    throw new Error(`Agent folder already exists: ${agentRoot}`)
+  }
+
+  const systemDir = path.join(agentRoot, 'system')
+  const skillsDir = path.join(agentRoot, 'skills')
+
+  fs.mkdirSync(systemDir, { recursive: true })
+  fs.mkdirSync(skillsDir, { recursive: true })
+
+  const createdPaths: string[] = []
+  const writeFile = (relativePath: string, content: string) => {
+    const absolutePath = path.join(agentRoot, relativePath)
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true })
+    fs.writeFileSync(absolutePath, content, 'utf8')
+    createdPaths.push(absolutePath)
+  }
+
+  const bootFileName = `boot.${AGENT_INITIAL_VERSION}.md`
+  const workflowFileName = `workflow.${AGENT_INITIAL_VERSION}.md`
+  const toolsFileName = `tools.${AGENT_INITIAL_VERSION}.json`
+  const modelFileName = `model.${AGENT_INITIAL_VERSION}.json`
+  const skillFileName = `${DEFAULT_SKILL_NAME}.${AGENT_INITIAL_VERSION}.md`
+  const activeSkillFileName = `${DEFAULT_SKILL_NAME}.active.md`
+
+  writeFile(path.join('system', bootFileName), buildBootDocument(normalizedAgentName))
+  writeFile(path.join('system', workflowFileName), buildWorkflowDocument(normalizedAgentName))
+  writeFile(path.join('system', toolsFileName), buildToolsConfig())
+  writeFile(path.join('system', modelFileName), buildModelConfig())
+  writeFile(path.join('system', 'prompt.ts'), SYSTEM_PROMPT_TS_TEMPLATE)
+
+  writeFile(path.join('skills', skillFileName), buildDefaultSkillDocument())
+  writeFile(path.join('skills', 'enabled-skills.md'), `${activeSkillFileName}\n`)
+  writeFile(path.join('skills', 'skills.ts'), SKILLS_TS_TEMPLATE)
+
+  writeFile('load.ts', LOAD_TS_TEMPLATE)
+
+  const createActiveLink = (versionedFile: string, activeFile: string) => {
+    const source = path.join(agentRoot, versionedFile)
+    const target = path.join(agentRoot, activeFile)
+    setActiveLink(source, target)
+    createdPaths.push(target)
+  }
+
+  createActiveLink(path.join('system', bootFileName), path.join('system', 'boot.active.md'))
+  createActiveLink(path.join('system', workflowFileName), path.join('system', 'workflow.active.md'))
+  createActiveLink(path.join('system', toolsFileName), path.join('system', 'tools.active.json'))
+  createActiveLink(path.join('system', modelFileName), path.join('system', 'model.active.json'))
+  createActiveLink(path.join('skills', skillFileName), path.join('skills', activeSkillFileName))
+
+  return {
+    agentName: normalizedAgentName,
+    agentRoot,
+    createdPaths: createdPaths.sort((a, b) => a.localeCompare(b)),
+  }
+}
+
+export function setActive(
+  agentName: string,
+  target: string,
+  processRoot: string = process.cwd(),
+  options: { latest?: boolean } = {}
+): ActiveFileResult {
+  const spec = parseTargetSpec(target)
+  const agentsRoot = resolveAgentsRootFrom(processRoot)
+  const targetDir = path.join(agentsRoot, agentName, ...spec.parts)
+  const agentDir = path.join(agentsRoot, agentName)
+
+  if (!existsDir(agentDir)) {
+    throw new Error(`Agent folder not found: ${agentDir}`)
+  }
+
+  if (!existsDir(targetDir)) {
+    throw new Error(`Target folder not found: ${targetDir}`)
+  }
+
+  const matchedFile = resolveTargetFile(targetDir, spec, options)
+  if (!matchedFile && !spec.version && options.latest) {
+    throw new Error(`No files found for /${spec.parts.join('/')}${spec.parts.length > 0 ? '/' : ''}${spec.base}`)
+  }
+  if (!matchedFile) {
+    if (!spec.version && !options.latest) {
+      throw new Error(
+        `Version missing for /${spec.parts.join('/')}/${spec.base}. Use --latest to select the latest version.`
+      )
+    }
+    const extensionHint = spec.ext ? `.${spec.ext}` : ' with any extension'
+    throw new Error(
+      `Versioned file not found for /${spec.parts.join('/')}/${spec.base}.${spec.version}${extensionHint}`
+    )
+  }
+
+  const sourceFile = path.join(targetDir, matchedFile)
+  const activeFile = path.join(targetDir, `${spec.base}.active${path.extname(matchedFile)}`)
+  const mode = setActiveLink(sourceFile, activeFile)
+
+  return {
+    agentName,
+    sourceFile,
+    activeFile,
+    matchedFile,
+    mode,
+  }
+}
+
+export async function loadAgent(agentName: string, processRoot: string = process.cwd()): Promise<AgentLoadResult> {
+  const agentsRoot = resolveAgentsRoot(processRoot)
+  const agentDir = path.join(agentsRoot, agentName)
+
+  if (!existsDir(agentDir)) {
+    throw new Error(`Agent folder not found: ${agentDir}`)
+  }
+
+  const loadFile = path.join(agentDir, 'load.ts')
+  if (!existsFile(loadFile)) {
+    throw new Error(`Load file not found for agent '${agentName}': ${loadFile}`)
+  }
+
+  validateActiveConfigInputs(agentDir)
+
+  const moduleUrl = pathToFileURL(loadFile).href
+  const module = await import(moduleUrl)
+  const loadFn = module.load
+
+  if (typeof loadFn !== 'function') {
+    throw new Error(`Load module for agent '${agentName}' must export a 'load' function.`)
+  }
+
+  return {
+    agentName,
+    loaded: await loadFn(),
+  }
+}
+
+type SpawnCodexResult = {
+  status: number | null
+  signal: NodeJS.Signals | null
+  error?: Error
+}
+
+type SpawnCodexFn = (args: string[]) => SpawnCodexResult
+
+function getCodexCommand(): string {
+  const override = process.env.F0_CODEX_BIN?.trim() ?? process.env.EXAMPLE_CODEX_BIN?.trim()
+  if (override) {
+    return override
+  }
+  if (process.platform === 'win32') {
+    // Prefer npm/pnpm cmd shim over stale codex.exe binaries.
+    return 'codex.cmd'
+  }
+  return 'codex'
+}
+
+const defaultSpawnCodex: SpawnCodexFn = (args) => {
+  const spawnOptions = {
+    stdio: 'inherit' as const,
+    env: process.env,
+  }
+
+  const primaryCommand = getCodexCommand()
+  const primary = spawnSync(primaryCommand, args, spawnOptions)
+  if (primary.error) {
+    const err = primary.error as NodeJS.ErrnoException
+    if (
+      process.platform === 'win32'
+      && !process.env.F0_CODEX_BIN
+      && !process.env.EXAMPLE_CODEX_BIN
+      && primaryCommand === 'codex.cmd'
+      && err.code === 'ENOENT'
+    ) {
+      return spawnSync('codex', args, spawnOptions)
+    }
+  }
+
+  return primary
+}
+
+function toExitCode(signal: NodeJS.Signals | null): number {
+  if (!signal) {
+    return 1
+  }
+  if (signal === 'SIGINT') {
+    return 130
+  }
+  if (signal === 'SIGTERM') {
+    return 143
+  }
+  return 1
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+async function resolvePromptValue(value: unknown): Promise<unknown> {
+  if (typeof value === 'function') {
+    return await value()
+  }
+  return value
+}
+
+function extractPromptString(value: unknown): string | null {
+  if (typeof value === 'string') {
+    return value
+  }
+  if (isRecord(value) && typeof value.prompt === 'string') {
+    return value.prompt
+  }
+  return null
+}
+
+export async function loadAgentPrompt(agentName: string, processRoot: string = process.cwd()): Promise<string> {
+  const agentsRoot = resolveAgentsRoot(processRoot)
+  const agentDir = path.join(agentsRoot, agentName)
+
+  if (!existsDir(agentDir)) {
+    throw new Error(`Agent folder not found: ${agentDir}`)
+  }
+
+  const promptFile = path.join(agentDir, 'system', 'prompt.ts')
+  if (!existsFile(promptFile)) {
+    throw new Error(`Prompt file not found for agent '${agentName}': ${promptFile}`)
+  }
+
+  const promptModuleUrl = pathToFileURL(promptFile).href
+  const promptModule = await import(promptModuleUrl)
+  const candidates = [
+    await resolvePromptValue(promptModule.prompt),
+    await resolvePromptValue(promptModule.agentConfig),
+    await resolvePromptValue(promptModule.default),
+  ]
+
+  for (const candidate of candidates) {
+    const promptText = extractPromptString(candidate)
+    if (promptText !== null) {
+      return promptText
+    }
+  }
+
+  throw new Error(`Prompt module for agent '${agentName}' must export a prompt string.`)
+}
+
+export async function runAgent(
+  agentName: string,
+  codexArgs: string[] = [],
+  processRoot: string = process.cwd(),
+  options: { spawnCodex?: SpawnCodexFn } = {}
+): Promise<AgentRunResult> {
+  const prompt = await loadAgentPrompt(agentName, processRoot)
+  const spawnCodex = options.spawnCodex ?? defaultSpawnCodex
+  const args = ['--config', `developer_instructions=${prompt}`, ...codexArgs]
+  const result = spawnCodex(args)
+
+  if (result.error) {
+    throw new Error(`Failed to start codex: ${result.error.message}`)
+  }
+
+  return {
+    agentName,
+    exitCode: typeof result.status === 'number' ? result.status : toExitCode(result.signal),
+  }
+}
+
+function validateActiveConfigInputs(agentDir: string): void {
+  const issues: string[] = []
+
+  const requiredInputs = collectActiveConfigInputs(agentDir)
+
+  for (const input of requiredInputs) {
+    if (!existsFile(input.path)) {
+      if (input.required) {
+        issues.push(`missing: ${path.relative(agentDir, input.path)}`)
+      }
+      continue
+    }
+
+    if (!isSymbolicLink(input.path)) {
+      issues.push(`not a symlink: ${path.relative(agentDir, input.path)}`)
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new Error(`Config input check failed: ${issues.join(', ')}`)
+  }
+}
+
+function collectActiveConfigInputs(agentDir: string): ActiveConfigInput[] {
+  const systemDir = path.join(agentDir, 'system')
+  const skillsDir = path.join(agentDir, 'skills')
+
+  const required: ActiveConfigInput[] = [
+    { path: path.join(systemDir, 'boot.active.md'), required: true },
+    { path: path.join(systemDir, 'workflow.active.md'), required: true },
+    { path: path.join(systemDir, 'tools.active.json'), required: true },
+    { path: path.join(systemDir, 'model.active.json'), required: true },
+  ]
+
+  const enabledSkillsPath = path.join(skillsDir, 'enabled-skills.md')
+  if (!existsFile(enabledSkillsPath)) {
+    return required
+  }
+
+  const lines = fs.readFileSync(enabledSkillsPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+
+  for (const line of lines) {
+    required.push({ path: path.join(skillsDir, line), required: true })
+  }
+
+  return required
+}
+
+function isSymbolicLink(filePath: string): boolean {
+  try {
+    return fs.lstatSync(filePath).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+export async function main(argv: string[], processRoot: string = process.cwd()): Promise<string> {
+  if (
+    argv.length === 0 ||
+    argv.includes('--help') ||
+    argv.includes('-h')
+  ) {
+    return usage()
+  }
+
+  const [scope, maybeAgentOrFlag, maybeTarget, ...rest] = argv
+  const listMode = scope === 'agents' && maybeAgentOrFlag === '--list'
+  const createMode = scope === 'agents' && maybeAgentOrFlag === 'create'
+
+  if (scope !== 'agents') {
+    throw new Error('Expected command `agents` as first positional argument.')
+  }
+
+  if (listMode) {
+    const unknownFlags = rest.filter(Boolean)
+    if (unknownFlags.length > 0) {
+      throw new Error(`Unknown flags for list mode: ${unknownFlags.join(', ')}`)
+    }
+    return listAgents(processRoot).join('\n')
+  }
+
+  if (createMode) {
+    if (!maybeTarget) {
+      throw new Error('Missing required argument: <agent-name>.')
+    }
+
+    const unknownFlags = rest.filter(Boolean)
+    if (unknownFlags.length > 0) {
+      throw new Error(`Unknown flags for create mode: ${unknownFlags.join(', ')}`)
+    }
+
+    const result = createAgent(maybeTarget, processRoot)
+    const displayPath = path.relative(processRoot, result.agentRoot) || result.agentRoot
+    return `[${CLI_NAME}] created agent: ${result.agentName} (${displayPath})`
+  }
+
+  const agentName = maybeAgentOrFlag
+  const target = maybeTarget
+  const setActiveRequested = rest.includes('--set-active')
+  const useLatest = rest.includes('--latest')
+
+  if (target === 'load') {
+    if (rest.length > 0) {
+      throw new Error(`Unknown flags for load mode: ${rest.join(', ')}`)
+    }
+    const result = await loadAgent(agentName, processRoot)
+    return JSON.stringify(result.loaded, null, 2)
+  }
+
+  if (target === 'run') {
+    const result = await runAgent(agentName, rest, processRoot)
+    if (result.exitCode !== 0) {
+      process.exitCode = result.exitCode
+    }
+    return ''
+  }
+
+  if (!agentName || !target) {
+    throw new Error('Missing required arguments: <agent-name> and <file-path>.')
+  }
+
+  if (!setActiveRequested) {
+    throw new Error('`--set-active` is required for this operation.')
+  }
+
+  const unknownFlags = rest.filter((arg) => arg !== '--set-active' && arg !== '--latest')
+  if (unknownFlags.length > 0) {
+    throw new Error(`Unknown flags: ${unknownFlags.join(', ')}`)
+  }
+
+  const result = setActive(agentName, target, processRoot, { latest: useLatest })
+  return `[${CLI_NAME}] set active: ${result.matchedFile} -> ${path.basename(result.activeFile)} (${result.mode})`
+}
+
+function existsDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function existsFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile()
+  } catch {
+    return false
+  }
+}