agent-integration

What this skill does

Integrate this agent repo with Veris from scratch.

This skill takes a repo from "plain customer agent source" to "Veris-ready and pushable." If the user provided a path to an agent repo, use that as the repo root. Otherwise use the current working directory.

Treat any existing `.veris/` files or old scaffold output as starting material only. Use the current bundled references in this skill as the source of truth for what you generate.

## Core framing: the agent is the constant, Veris is the test harness

Veris exists to test an agent under realistic conditions. The agent is the thing being tested; Veris is the harness around it. That asymmetry drives every decision in this skill:

- **The agent runs the same way in Veris as it does in production.** If the agent speaks HTTP to a Slack Web API in prod, it speaks HTTP to the Veris Slack mock in sim. If it shells out to a CLI in prod, it shells out in sim. No special simulation code path.
- **All integration work lives in `.veris/`.** `.veris/veris.yaml`, `.veris/Dockerfile.sandbox`, `.veris/config.yaml`, `.veris/.dockerignore` are the deployment descriptor — the equivalent of a Helm chart or `docker-compose.yaml` for this agent. They describe *how to stand the agent up for this environment*. They do not contain behavior that belongs inside the agent.
- **Do not write wrappers, shims, or glue code that "adapts" the agent to Veris.** A Python file that wraps a CLI agent to expose a callable, a script that translates Veris's actor format into the agent's native format, a patched version of the agent that accepts Veris-specific parameters — all of these are the wrong shape. They mean the thing you end up testing is not the agent.
- **Do not modify the agent's source code to make it work in Veris.** If the agent assumes something Veris can't satisfy as-is, that's either a Veris platform gap to be logged, or a real issue with the agent that would also break production. Either way, the fix does not belong in the agent's source.
- **If you find yourself needing a wrapper, stop and treat it as a finding.** Ask: what is the agent's real production integration path? If the agent has an HTTP server in prod, use that. If it's CLI-only in prod and Veris's actor can't drive a CLI, escalate — that's a Veris capability gap, not a license to invent glue.
- **The one legitimate `.veris/` file that is not pure config is a container-orchestration `start.sh`** for bundling multiple processes (e.g., a database alongside the agent). Even that starts and runs the agent as-shipped; it does not transform its behavior.

When in doubt: the agent's author should be able to read `.veris/` and recognize it as "the deploy config for Veris," not as "someone forked and patched my agent."

### Transport bridges are an explicit exception

A **transport bridge** translates between the actor's channel format (e.g. `voice_ws` PCM16) and the agent framework's native transport (e.g. LiveKit WebRTC, SIP media, a proprietary message envelope) while preserving the underlying payload byte-for-byte. It is *not* a wrapper. The same shape exists in production for the agent's other product surfaces — mobile clients, kiosks, IVR vendors — so the bridge is genuine product code, not Veris-specific glue.

A bridge is allowed when:

- The agent's framework cannot be reconfigured to speak the actor's channel format directly (e.g., LiveKit Agents is WebRTC end-to-end and has no raw-PCM16-WS transport).
- The bridge is pure transport translation: same audio bytes / same JSON payloads in and out, with no semantic reshaping. (For voice, the audio bytes the agent's model receives must be identical to what the actor sent. For text, the message payload the agent sees must be identical to what the actor sent.)
- The bridge lives in the agent's repo as production code (e.g., `app/bridge.py`), exercised by the agent's own tests — not in `.veris/`. It is the agent's `voice_ws`-on-WebRTC product surface; Veris is just one caller.

A bridge is **not** allowed when:

- It reshapes content the agent sees: rewriting messages, restructuring tool-call JSON, normalizing STT output, translating Veris-specific actor fields into the agent's native parameters. That is a wrapper, and the no-wrapper rule above applies.
- The framework *can* be configured to speak the actor's channel (Pipecat with `RawAudioFrameSerializer` for `voice_ws`, the framework's own HTTP plugin for `http`, etc.). Configure the framework first; bridge only if the transport is fixed.

Quick rubric: "same bytes, different network format" = transport bridge (allowed). "Different bytes / different shape" = wrapper (not allowed).

See [reference/infrastructure-patterns.md Pattern 9](reference/infrastructure-patterns.md#pattern-9-transport-bridge) for the architecture and [reference/voice-channels.md](reference/voice-channels.md) for the voice-specific application.

### Reporting client-tool calls to the grader is a sanctioned exception (voice agents only)

This is the one exception that genuinely breaks the "no Veris-specific code path" rule — and it is deliberate. It applies only to **voice agents built on hosted speech-to-speech platforms** (ElevenLabs Conversational AI, OpenAI Realtime, Gemini Live, Vapi, and the like) whose tools execute inside the agent process — as **client tools** that round-trip on the vendor's WebSocket, or as Vapi-style **server tools** the platform POSTs back to the agent's webhook over HTTP. Either way the call never reaches the spoken transcript.

Why it's needed: the voice grader builds its trace from the spoken transcript plus any tool-call events the agent reports. A client tool never reaches the transcript, so without a report the grader can't see the tool ran and false-flags real actions (a card freeze, a replacement) as hallucinations. Text/HTTP agents don't have this problem — their tool calls are captured automatically — so this exception is voice-only.

The fix: after each tool runs, the agent POSTs an `agent_tool_call` event to the sandbox engine, and the platform renders it into the graded trace. Keep it strictly minimal so it stays instrumentation, not a wrapper:

- **No-op outside a simulation.** Gate on `SIMULATION_ID` (unset in production → return immediately). Production behavior is unchanged.
- **Fire-and-forget, fail-soft.** Short timeout, swallow errors, log a warning. A reporting failure must never break the call or change the agent's output.
- **Observe, don't reshape.** Report *after* the real tool runs, passing the real name/args/result through unchanged. It records what happened; it does not alter what the agent does or what the model sees.

This is sanctioned only for client-tool grader visibility, only for voice agents, and only in this minimal shape — it is not a license for general shims. The exact endpoint, event schema, and a copy-paste hook are in [reference/voice-channels.md](reference/voice-channels.md#making-client-tool-calls-visible-to-the-grader).

## Core rules

- Explain what you are about to do before each major step.
- Surface decisions with real tradeoffs and let the user choose.
- Cite concrete evidence from the repo when you classify dependencies or decide how the agent should be integrated.
- Do not silently preserve stale Veris config. Migrate it to the current preferred shape.
- Do not generate `.env.simulation`. The current runtime flow is `agent.environment` plus `veris env vars set`.
- Prefer the current `actor.channels` schema and canonical service names. Do not generate legacy `persona.modality`, `email_address`, or old service aliases unless the user explicitly asks for compatibility.
- Do not write Python wrappers, shell shims, or any "adapter" code that translates between Veris and the agent. Use the agent's real production interface. If that isn't possible as-is, surface it as a platform gap, not as a wrapper opportunity.
- Ask before external or irreversible actions:
  - installing `veris-cli`
  - running `veris login`
  -