docs(cloud-agents): add multi-harness pages (Warp Agent, Claude Code, Codex)#87
docs(cloud-agents): add multi-harness pages (Warp Agent, Claude Code, Codex)#87hongyi-chen wants to merge 4 commits into
Conversation
Add a new harnesses section under agent-platform/cloud-agents documenting the harnesses available inside Oz (Warp Agent, Claude Code, Codex), plus a procedural authentication page for connecting Anthropic and OpenAI credentials. Add 'two contexts' callouts to the existing CLI-agent pages distinguishing the local terminal toolbelt from the cloud orchestration surface, and cross-link to the new harness pages. New pages: - agent-platform/cloud-agents/harnesses/index.mdx (overview) - agent-platform/cloud-agents/harnesses/warp-agent.mdx - agent-platform/cloud-agents/harnesses/claude-code.mdx - agent-platform/cloud-agents/harnesses/codex.mdx - agent-platform/cloud-agents/harnesses/authentication.mdx Edited pages: - agent-platform/cli-agents/overview.mdx (two-contexts callout) - agent-platform/cli-agents/claude-code.mdx (cross-link) - agent-platform/cli-agents/codex.mdx (cross-link) - agent-platform/cli-agents/opencode.mdx (fast-follow note) Sidebar wiring is intentionally deferred to the cross-cutting sidebar PR per the orchestration launch tracker. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds a new multi-harness documentation section plus cross-links from the existing CLI-agent pages. The security pass did not find security-specific issues in the docs-only diff.
Concerns
- The new harness pages are not added to the Starlight sidebar topic configuration, which leaves the branch unable to build as a standalone PR.
- Several user-facing availability claims overstate which surfaces can launch each harness today.
- The billing and Codex model guidance conflicts with the credential/authentication flows documented in the same PR.
Verdict
Found: 0 critical, 4 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| @@ -0,0 +1,71 @@ | |||
| --- | |||
There was a problem hiding this comment.
src/sidebar.ts leaves them outside any starlight-sidebar-topics topic, so npm run build fails; wire the new harnesses pages into the Agents sidebar in this PR or remove these pages/links until the sidebar PR lands.
There was a problem hiding this comment.
Intentionally not addressed in this PR — src/sidebar.ts is owned by the gating-branch coordination PR (hyc/orchestration-launch), not by any single workstream PR. The sidebar wiring for all the new harness pages will land alongside the gating-branch merge so we're not racing other workstream PRs on the same file.
|
|
||
| A harness is the agent runtime that executes a cloud agent run. Oz lets you pick the harness that fits the task — [Warp Agent](/agent-platform/cloud-agents/harnesses/warp-agent/), [Claude Code](/agent-platform/cloud-agents/harnesses/claude-code/), or [Codex](/agent-platform/cloud-agents/harnesses/codex/) — without changing how you launch, observe, or govern the run. | ||
|
|
||
| Every harness is a first-class citizen on the [Oz Platform](/agent-platform/cloud-agents/platform/). You can launch and steer any harness from the Warp terminal, the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), the [Oz CLI](/reference/cli/), the [REST API or SDK](/reference/api-and-sdk/), and direct it to do work across multiple repos, integrations, and machines. The harness changes; the platform around it does not. |
There was a problem hiding this comment.
There was a problem hiding this comment.
Addressed in 51e6baa. The overview's "How to switch harnesses" section now lists per-surface availability instead of claiming all harnesses run on all surfaces: Warp app dropdown is Warp Agent / Claude Code / Gemini today; the Oz CLI accepts oz, claude, gemini (Codex CLI selection is a fast-follow); the Oz web app and API/SDK expose all four. The Codex page repeats the CLI-and-Warp-app fast-follow in a caution block so readers don't try to follow steps that aren't wired yet.
| * **Cloud orchestration** - Launch Claude Code from any Oz trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions. | ||
| * **Claude model picker** - Choose the Claude model the harness uses, including the latest pinned Opus, Sonnet, and Haiku releases, the `best`/`opus`/`sonnet`/`haiku` aliases, and 1M-context variants. | ||
| * **Shared platform context** - Reads the same [environments](/agent-platform/cloud-agents/environments/), [agent secrets](/agent-platform/cloud-agents/secrets/), [MCP servers](/agent-platform/cloud-agents/mcp/), and [Skills](/agent-platform/capabilities/skills/) used by every other harness. | ||
| * **One credit pool** - Claude Code runs bill against your Warp credits like any other cloud agent run. There's no separate Anthropic contract or seat count. |
There was a problem hiding this comment.
There was a problem hiding this comment.
Addressed in 51e6baa. The "one credit pool" claim is gone. The overview, Claude Code, Codex, and authentication pages now align on the same story: customer-supplied Anthropic/OpenAI API keys mean the provider bills your account directly for inference; Warp credits cover the platform layer (environment compute, triggers, observability) only. The "Credentials and billing" section on each third-party harness page makes this explicit.
|
|
||
| The Codex harness exposes OpenAI's Codex-tuned and general coding models. Common picks: | ||
|
|
||
| * `default` - Lets Codex pick its own recommended model (GPT-5.5 for ChatGPT-authenticated users, GPT-5.4 otherwise). |
There was a problem hiding this comment.
openai_api_key, so ChatGPT-authenticated defaults are not actionable here; either document ChatGPT auth for cloud Codex runs or remove the ChatGPT-only model guidance from this page.
There was a problem hiding this comment.
Addressed in 51e6baa. Cloud Codex only supports openai_api_key today, so the ChatGPT-auth caveat was misleading. The models list now describes default as "Codex picks its own recommended model based on the API key's account access" with a follow-up sentence telling the reader to pick default if they're unsure which models their key is entitled to. No more ChatGPT-only model claim.
…ology - Retitle harness pages to "Warp Agent with Oz", "Claude Code with Oz", "Codex with Oz"; index becomes "Harnesses in Oz". Update body copy and cross-references in cli-agents/* to match. - Reconcile billing claim: customer-supplied Anthropic and OpenAI API keys mean the provider bills your account directly for inference; Warp credits cover the platform layer only. Apply across overview, Claude Code, Codex, and authentication pages. - Remove ChatGPT-auth ambiguity from Codex model list; "default" now reads as "Codex picks its own recommended model" with no provider- account claim that does not match cloud auth options. - Qualify launch surfaces accurately: Warp terminal harness dropdown lists Warp Agent, Claude Code, Gemini today (no Codex); Oz CLI accepts --harness oz|claude|gemini today (Codex is fast-follow); Oz web app and API/SDK expose all four harnesses. Mark Codex CLI selection as fast-follow in the Codex page and authentication page. - Add conservative framing for Gemini and OpenCode harnesses on the overview. - Strip internal field-name jargon from user-facing examples. Co-Authored-By: Oz <oz-agent@warp.dev>
Revision pass on Slack-thread feedback + bot review (commit 51e6baa)Addressed the four reviewer-flagged items plus the broader Slack-thread "Oz harness" reframe: Terminology reframe (Petra / Olivia / Ryan feedback)
Reviewer comments
Additional changes
Validation: |
…it implementation detail Address Slack-thread feedback on PR #87: - Drop OpenCode from the harnesses overview roadmap note and remove the OpenCode-in-Oz callout from cli-agents/opencode.mdx. OpenCode is no longer mentioned anywhere in the harness docs. - Replace the six-sentence 'two contexts' callout on cli-agents/overview with a two-sentence note: Claude Code and Codex are also supported as harnesses in Oz. The matching callouts on cli-agents/claude-code and cli-agents/codex shrink to the same shape. - Audit pass for over-explanation: harness 'How it works' sections drop Docker / cli-invocation walk-throughs in favor of user-facing copy; Claude and Codex model lists trim in-product aliases (opus[1m], sonnet[1m], opusplan, gpt-5.3-codex-spark, etc.) and defer to the picker for the full list; 'What stays the same' bullets lead with the user benefit; the authentication intro and BYOK callouts drop 'cloud container' / 'injected at runtime' phrasing. Co-Authored-By: Oz <oz-agent@warp.dev>
- Replace "the default Oz harness" with "Oz's default harness" in Related-pages bullets to avoid the "Oz harness" noun-phrase. - Sweep "on Oz" → "with Oz" across harness page descriptions and body copy. - Drop preview/fast-follow hedges around Codex CLI launch and the Warp app's harness dropdown — treat as launching at GA. - Rewrite "GPT-5.5 family" as "the GPT-5 lineup" and drop gpt-5.5 from the cloud Codex Common picks (gpt-5.5 is ChatGPT-auth only; cloud Codex authenticates with an OpenAI API key). gpt-5.4 is now framed as the recommended cloud Codex default. - Add the \`best\` alias to the Claude Code Common picks list with a note that it resolves to the current top-of-line Claude model. Co-Authored-By: Oz <oz-agent@warp.dev>
|
Applied the approved audit fixes in 58739b0:
One judgment call: kept the
|
1 participant
Summary
Adds the documentation for the multi-harness story in the Oz Orchestration Launch (Codename Maestro): customers can now launch and steer Warp Agent, Claude Code, and Codex as first-class harnesses inside Oz from the Warp terminal, the Oz web app, the Oz CLI, the REST API, or the SDK. One access-control, environment, secret, observability, governance, and billing model spans every harness.
This PR ships five new pages under
agent-platform/cloud-agents/harnesses/(conceptual overview, per-harness feature docs for Warp Agent / Claude Code / Codex, and a procedural authentication page for connecting Anthropic and OpenAI credentials), and adds short "two contexts" callouts to the existing CLI-agent pages so readers can tell the local Warp-terminal experience apart from the cloud harness experience. OpenCode and Gemini are flagged as fast-follow harnesses where it's natural to do so.New pages
src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx— Harnesses overview. What a harness is, harness vs. model, what stays the same across harnesses, how to choose, how to switch.src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx— Warp Agent harness. Default; multi-model auto-routing; full terminal/tool access; Skills/Rules/Memory/Codebase Context native support; cross-harness orchestration parent.src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx— Claude Code harness. Cloud orchestration, Claude model picker (opus/sonnet/haiku, 1M-context variants), credential types, choosing-Claude heuristics, how to launch from every surface.src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx— Codex harness. Cloud orchestration, Codex model picker (GPT-5.5 / GPT-5.4 / Codex-tuned variants), credential type, choosing-Codex heuristics, how to launch.src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx— One-time auth setup for Claude Code and Codex via Warp-managed secrets (Oz web app and Oz CLI), with rotation/deletion guidance and troubleshooting.Edited pages
src/content/docs/agent-platform/cli-agents/overview.mdx— Added a "Two contexts for these agents" callout up top distinguishing the Warp-terminal experience from the Oz cloud harness experience, with a link to the new harnesses overview.src/content/docs/agent-platform/cli-agents/claude-code.mdx— Added a top-of-page callout linking to the Claude Code harness page; added the harness page to "Related pages".src/content/docs/agent-platform/cli-agents/codex.mdx— Same treatment as Claude Code.src/content/docs/agent-platform/cli-agents/opencode.mdx— Noted that OpenCode as an Oz cloud harness is a fast-follow with a link to the harnesses overview.Research grounding
Confirmed against
warp-serverandwarp-internal:model/types/enums/agent_harness.godefinesOZ,CLAUDE_CODE,GEMINI,CODEX. Per-harness feature flags + admin-disable via workspace settings, plus theOzMultiHarnessExperimentarm gate in production (logic/harness_availability.go).config/harness_models.goconfirms the Claude model picker (opus/sonnet/haiku aliases, pinnedclaude-opus-4-7etc.,opus[1m],sonnet[1m],opusplan) and the Codex picker (default,gpt-5.5,gpt-5.4,gpt-5.4-mini,gpt-5.3-codex-spark,gpt-5.3-codex,gpt-5.2).model/types/enums/managed_secret_type.goconfirms the auth-secret types per harness:anthropic_api_key/anthropic_bedrock_api_key/anthropic_bedrock_access_keyfor Claude Code,openai_api_keyfor Codex.HarnessSelectorandHarnessAuthSecretSelector(client/packages/agents/src/components/) confirm the new-run and new-schedule UI flows.crates/warp_cli/src/agent.rsconfirmsoz agent run --harnessandoz agent run-cloud --harnesswith--claude-auth-secret.crates/warp_cli/src/secret.rsconfirmsoz secret create anthropic api-key|bedrock-api-key|bedrock-access-key.Caveats / open questions for product / PM
Harnessclap enum listsoz,claude,geminionly — nocodexvalue yet. There's also no--codex-auth-secretflag and nooz secret create openaiprovider subcommand. The Codex harness page reflects this and steers CLI-first users toward the Warp app / Oz web app. Please confirm timing of CLI catch-up so the page can be amended.app/src/terminal/view/ambient_agent/harness_selector.rsrenders Oz / Claude / Gemini. If Codex is expected to be live in Cloud Mode's harness dropdown at launch, the menu needs updating; otherwise I should re-word the "Warp app" steps to say Codex starts from the Oz web app today.--harness gemini, terminal selector), so saying both are "coming soon" is slightly conservative. I've labeled both as fast-follow on the harnesses overview and as a "coming soon" note on the OpenCode page. Please confirm this matches marketing copy.src/sidebar.tsper the orchestration launch file-scope guidance — the cross-cutting sidebar PR will add the five new pages to theAgentstopic. As a result,npm run buildcurrently fails on this branch withAstroUserError: Failed to find the topic for the agent-platform/cloud-agents/harnesses pageuntil the sidebar PR lands. If the cross-cutting PR is meant to land later, this PR can merge first; the build will resolve once both are on the gating branch. Flagging in case the sequencing needs adjusting.HarnessAuthSecrets.codex_auth_secret_namefield. APP-4374 introduces this on the agent-config snapshot; the Codex page and authentication page reference it. Confirm it's shipping in the launch window so the doc isn't ahead of the SDK.Validation
AGENTS.md.harnesses/...paths consistently.ManagedSecretTypeenum (anthropic_api_key,anthropic_bedrock_api_key,anthropic_bedrock_access_key,openai_api_key).Co-Authored-By: Oz oz-agent@warp.dev