Ruhroh

Appearance

Agent Command Protocol ​

Agent connectors own agent-specific behavior. Ruhroh owns the task loop and result mapping.

Most users should use the command-backed path documented in Connect an Agent and Run a Shell Agent. A command wrapper is easier to audit, works with existing agent CLIs, and already supports completion status, transcripts, model identity, usage, and evidence metadata through RUHROH_RESULT_PATH.

Use the TypeScript connector lifecycle only for advanced integrations where a process wrapper cannot preserve the agent behavior you need, for example a native session transport, embedded SDK client, or custom evidence collection.

For shell-based public agents, use the generic command protocol. Ruhroh passes:

  • RUHROH_MESSAGE
  • RUHROH_ITERATION
  • RUHROH_WORKSPACE
  • RUHROH_GOAL_PATH
  • RUHROH_WORKSPACE_PATH
  • RUHROH_RESULT_PATH
  • RUHROH_SESSION_HANDLE
  • RUHROH_SCENARIO_ID
  • RUHROH_RUN_ROOT
  • RUHROH_ADAPTER_ID
  • RUHROH_SAMPLE_ID
  • RUHROH_SAMPLE_SEED
  • RUHROH_RUN_INDEX
  • RUHROH_RUN_COUNT

Wrappers should emit a final JSON line:

json
{"status":"goal_satisfied"}

Wrappers may also write RUHROH_RESULT_PATH with version: "ruhroh_run_agent_result_v1". Ruhroh reads that file when present and maps goal_satisfied, continue, cannot_satisfy, policy_blocked, runtime_failure, and infra_failure into the generic completion contract.

The result file may include connector-specific metadata:

json
{
  "version": "ruhroh_run_agent_result_v1",
  "status": "goal_satisfied",
  "runId": "agent-run-123",
  "adapterVersion": "1.4.0",
  "model": {
    "provider": "example",
    "model": "agent-model",
    "version": "2026-07-07",
    "promptVersion": "adapter-prompt-v3"
  },
  "usage": {
    "costUsd": 0.42,
    "inputTokens": 1200,
    "outputTokens": 800,
    "totalTokens": 2000
  },
  "artifacts": {
    "transcript": "/path/to/transcript.log"
  }
}

Ruhroh copies adapterVersion, model, and usage from the latest command result into ruhroh-run-manifest.json. These values take precedence over env fallbacks for the same run.

For reproducible reports, wrappers or launch scripts may set:

  • RUHROH_RUN_AGENT_ADAPTER_VERSION
  • RUHROH_AGENT_PROVIDER
  • RUHROH_AGENT_MODEL
  • RUHROH_AGENT_MODEL_VERSION
  • RUHROH_AGENT_PROMPT_VERSION
  • RUHROH_RUN_SEED
  • RUHROH_RETRY_POLICY
  • RUHROH_COST_USD
  • RUHROH_INPUT_TOKENS
  • RUHROH_OUTPUT_TOKENS
  • RUHROH_TOTAL_TOKENS

Ruhroh writes these into ruhroh-run-manifest.json when present. Secret values are not copied into the manifest.

Advanced TypeScript Lifecycle ​

The TypeScript adapter contract is exported from @kestrel-agents/ruhroh:

  • prepare()
  • startSession()
  • runTurn()
  • detectCompletion()
  • collectArtifacts()
  • cleanup()

Connectors report their continuity level:

  • native_session
  • workspace_plus_transcript
  • workspace_only