Skip to content

AI Agent (Runtime Agent)

An AI coding agent (Claude Code, Cursor, or any other) can drive Engineering Runtime only through the runtime binary. It must not call gh, kubectl, terraform, curl, or arbitrary shell for engineering work.

Engineer → natural language → Runtime Agent
                                    ↓
                              runtime binary
                 (Bootstrap → Context → Policy → Auth →
                          Execution → Audit)
                                    ↓
                           Engineering platforms

The contract repository is engineering-runtime-ai-agent. It holds no engines and no providers — execution always belongs to the installed runtime binary.

Why this exists

Without enforcement, agents drift into direct tool use and bypass policy and audit. The Runtime Agent layer makes the boundary mechanical:

Piece Role
CLAUDE.md / Cursor rules Reason only about runtime commands and capabilities
Skills Discover commands, author capabilities, hand off
Claude Code hooks Bash must be runtime …
Cursor hooks beforeShellExecution / Shell preToolUse deny non-runtime

Prerequisites

  1. Install runtime — Installation
  2. Bootstrap and confirm:
runtime bootstrap
runtime version
runtime config validate
  1. Authenticate platforms the agent will use (e.g. RUNTIME_GITHUB_TOKEN)
  2. Open engineering-runtime-ai-agent (or copy its hooks/rules into your project) so the shell policy applies
  3. Label audit records:
export ENGINEERING_RUNTIME_CONSUMER=ai

How the agent is supposed to work

  1. Understand intent from the engineer.
  2. Discover what this installed binary can do — prefer Runtime Home contracts after bootstrap:
Path Role
${ENGINEERING_RUNTIME_HOME:-~/.engineering-runtime}/commands/ Command cheatsheets
…/specs/ Capability grammar + per-provider authoring specs
…/capabilities/ or RUNTIME_CAPABILITIES_DIR Reusable workflows

Live discovery (preferred over memorizing):

runtime config validate          # providers + allowed binaries
runtime github --help
runtime files --help
runtime resolve github repo list # does this command exist?
  1. Resolve an existing capability, or author a Markdown capability that only uses published provider operations / allowed binaries.
  2. Hand off:
runtime capability validate <name-or-path>
runtime capability execute <name-or-path> --input k=v …
# or a direct provider operation:
runtime github repo view cli/cli

Prefer a provider operation when one exists. Use runtime command run <binary> … only when the intent is a raw allowed CLI no provider covers. Never bypass with bare helm / gh / curl.

Two surfaces (both via runtime only)

Surface Form Discover from
Runtime Provider runtime github … / runtime files … runtime config validate → Runtime Providers; --help
Command Engine runtime command run <binary> … runtime config validate → allowed_binaries; Home commands/<binary>_commands.txt

If neither surface covers the request (e.g. "create a Jira card" with no jira provider and no jira binary), the agent must refuse — not invent a bypass.

Cursor setup

In engineering-runtime-ai-agent:

Path Effect
.cursor/hooks.json beforeShellExecution + Shell preToolUse
.cursor/hooks/runtime-only-shell.sh Deny unless command is runtime …
.cursor/rules/ Always-on: runtime-only reasoning

After changing hooks, confirm they load in Cursor Settings → Hooks. Restart Cursor if a new hooks.json does not appear. failClosed: true means a broken hook blocks the command.

Claude Code setup

Path Effect
.claude/settings.json Registers Bash hooks
.claude/hooks/runtime-only-shell.sh Same allow/deny policy
scripts/runtime-shell-policy.sh Shared policy with Cursor

Authoring capabilities as an agent

Capabilities are Markdown with one ```runtime block. Grammar: Authoring reference.

Rules that matter for agents:

  • Exactly one of provider: or binary: per step
  • Never write a transport: key — the provider owns that
  • Validate before execute
  • A capability gets no special powers — each step hits the same policy/auth/audit path

Reusable company capabilities belong in engineering-runtime-capabilities, not only in a single machine's Home.

What the agent must not do

  • Call platform CLIs or HTTP clients directly for engineering work
  • Invent provider operations that runtime <provider> --help does not list
  • Depend on a transport ("use the REST one")
  • Disable or work around the shell hooks

End-to-end check

export ENGINEERING_RUNTIME_CONSUMER=ai
export RUNTIME_GITHUB_TOKEN=ghp_…

runtime bootstrap
runtime config validate
runtime capability validate files/notes-roundtrip
runtime capability execute files/notes-roundtrip \
  --input path=./agent-note.txt --input message="from Runtime Agent"
runtime audit tail -n 5

Ask the agent something that should fail policy (e.g. force-push) and confirm it is denied and audited — not executed via raw git.

Next