Add a Ruby UTCP coding-agent example with approvals and Code Mode

Closed
RA
2mo ago
+1331-0

Summary

Adds examples/coding_agent.rb, a terminal coding agent with one-shot and interactive modes, OpenRouter-compatible chat completions, six workspace tools, and optional UTCP Code Mode.

  • Tool discovery, schemas, namespacing and invocation use the actual UTCP client through an example-local, in-process coding_agent_local protocol. Existing SDK transports are unchanged.
  • File edits and every command require approval by default. Read-only mode, SHA-256 revision checks, bounded output, command process-group timeouts, and per-task tool budgets are enforced below the model layer.
  • The agent preserves tool-call IDs and opaque provider reasoning metadata, handles malformed arguments/tool errors, and reports iteration exhaustion without claiming success.
  • Adds a usage/security guide and an entry in examples/README.md.

Run

export OPENROUTER_API_KEY='your-key'
export OPENROUTER_MODEL='your-tool-capable-model-id'
bundle exec ruby -Ilib examples/coding_agent.rb --workspace /path/to/project --codemode

Use --prompt 'task' for one-shot mode and --read-only to prohibit edits and commands.

Verification

Locally verified on Ruby 3.3.8: 26 tests, 100 assertions, 0 failures, 0 errors, 0 skips, plus Ruby syntax checks and CLI help. HTTP tests use a local TCP server; provider/client doubles are explicit in agent-loop unit tests.

A separate test/coding_agent_utcp_test.rb uses the real SDK in a subprocess to verify discovery, invocation, Code Mode edits, approval enforcement, client isolation and call budgets. It is included in the existing rake test discovery. The complete SDK cannot be installed in the local execution environment, so real-SDK/full-suite verification was performed by repository CI instead.

Latest commit 1394950: all eight CI test/gem-build jobs passed on Ruby 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, 3.4, and 4.0. These jobs run the complete unit/regression suite, including the real-SDK integration test. The coverage-and-transports job also passed. The transport-soak and native-transports jobs were still running at the last check; no claim of a fully completed workflow is made.

CI run: https://github.com/universal-tool-calling-protocol/ruby-utcp/actions/runs/34507245625

The first run exposed an older-Ruby test-loader error (require_relative inside ruby -e). Commit 1394950 fixed it using an explicit absolute require path; the corrected Ruby 2.6 and 2.7 jobs are green.

No paid/live LLM call was performed.

Security scope

These are application guardrails, not an OS sandbox. Approved commands can execute arbitrary code with the user's permissions. --yes explicitly auto-approves both edits and commands; read-only mode still wins. Source/tool output is sent to the configured LLM provider. Code Mode batches are not transactions, and completed edits are not automatically rolled back. The example does not automatically commit or push workspace changes.