# Runtime and Agent Registry Implementation

Date: 2026-07-06

## Goal

Separate execution infrastructure from agent behavior:

- Runtime registration answers where AI work runs: AgentRun, local Codex CLI, local Qoder, WorkBuddy, Trae Work, or future remote endpoints.
- Agent registration answers how a scenario runs: prompt, attached system Skill, selected runtime, and effective places such as create, evaluate, and run.

## Research Notes

The useful pattern from local/remote runtime products is to treat runtime as an execution substrate, not as a model provider. Local runtimes are usually installed commands invoked in a task workspace. Remote runtimes are service endpoints with credentials. The product should first register runtimes, then bind agents to runtimes by scenario.

## Data Model

`runtime_engines` remains the canonical runtime table and now supports both remote and local runtimes.

New runtime fields:

- `local_command`
- `local_args_json`
- `local_healthcheck_args_json`
- `local_working_dir`
- `local_env_json`
- `purpose_scopes_json`
- `timeout_ms`
- `notes`

New `runtime_agents` table:

- `id`
- `name`
- `description`
- `prompt`
- `system_skill_kind`
- `runtime_code`
- `applies_to_json`
- `enabled`
- `updated_at`

Default runtime rows:

- `agentrun`
- `local-codex`
- `local-qoder`
- `local-workbuddy`
- `local-trae`

Default agent rows:

- Skill creator: applies to `create`
- Skill evaluator: applies to `evaluate`
- Skill runner: applies to `run`

## Runtime Resolution

For each scenario, the backend resolves:

1. Enabled agent whose `applies_to_json` contains the scenario.
2. The agent runtime when configured and enabled.
3. Otherwise the active enabled runtime scoped to the scenario.

The Skill run stream now uses this resolution for:

- `mode=create`
- `mode=evaluate`
- `mode=run`

The public Skill invoke API also resolves the `run` runtime.

## Local CLI Execution

Local CLI runtimes execute in the Skill session directory. Runtime arguments may include `{workdir}`, which expands to that directory. The platform sends the merged agent prompt, system Skill prompt, and user messages to stdin.

Runtime arguments may also include `{prompt}` for CLIs that require the prompt as a positional argument instead of reading stdin.

Default Codex command:

```text
codex
```

Default Codex args:

```text
exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox -C {workdir} -
```

Health check uses:

```text
--version
```

## UI

The existing model settings page now has:

- Model provider configuration
- System Skill configuration
- Runtime registry
- Agent registry

Runtime registry supports:

- Enable/disable
- Test connectivity
- Set active runtime
- Local command, args, health check args, env vars, working directory, timeout
- Purpose scopes

Agent registry supports:

- Prompt editing
- System Skill attachment
- Runtime selection
- Effective scenario selection

## Verification

Regression commands run:

```bash
npm run build
node --test src/services/*.test.js
node --test cf-worker/src/runtime/*.test.js cf-worker/src/routes/*runtime*.test.js cf-worker/src/routes/skill-run-*.test.js
```

Manual verification:

- Applied database migrations with `node scripts/db-init.cjs`.
- Started local backend on `http://localhost:4000`.
- Started Vite on `http://127.0.0.1:5173`.
- Verified `/api/runtimes` returns AgentRun plus local CLI runtimes.
- Verified `/api/runtimes/local-codex/test` returns the installed Codex CLI version.
- Verified the settings page renders runtime and agent registry panels with Playwright screenshots.

## Local Runtime Wiring on This Machine

Configured and enabled:

- `local-codex`: `/Users/Administrator/.npm-global/bin/codex`
- `local-qoder`: `/Users/Administrator/.local/bin/qodercli`
- `local-trae`: `/Users/Administrator/.local/bin/trae-cli`
- `local-workbuddy`: `/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy`

Health checks:

- Codex: `codex-cli 0.141.0`
- Qoder: `0.2.6`
- Trae: `trae-cli version 0.120.42`
- WorkBuddy: `2.103.3`

Real prompt execution using `RUNTIME_OK`:

- Codex: passed.
- WorkBuddy: passed.
- Qoder: blocked by duplicate Skill conflicts between `~/.agents/skills` and `~/.qoder/skills`.
- Trae: CLI starts, but real execution reports missing model configuration (`Models is required`).
