docs: remove experimental framing from Computer Use, update to enabled-by-default - #395
docs: remove experimental framing from Computer Use, update to enabled-by-default#395warp-dev-github-integration[bot] wants to merge 5 commits into
Conversation
…d-by-default Computer use in Oz is now a first-class, non-experimental capability enabled by default for cloud runs. Update docs to reflect this: - Remove 'experimental feature' label from opening paragraph and security considerations section - Change 'opt-in and disabled by default' → 'enabled by default for Oz cloud runs' - Reframe 'Enabling' section as 'Configuring' to match the new defaults - Add Oz web app subsection noting computer use is on by default; to disable, deselect the Computer use checkbox - Update API section: omitting computer_use_enabled now enables computer use; show false as the disable option, document explicit true as equivalent to omitting - Scope the Warp desktop app toggle precisely as a desktop-client-only setting with a callout clarifying it does not affect web/API defaults - Update anchor link in computer-use-testing-and-recordings.mdx to match the renamed section heading (#configuring-computer-use) Relates to REMOTE-2358 Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@warp-dev-github-integration[bot] 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 updates the Computer Use documentation to remove experimental framing and document the new enabled-by-default behavior for Oz cloud runs.
Concerns
- The Computer Use page now tells API callers that omitting
computer_use_enabledenables computer use, but the linked generated API reference still documents the same field as defaulting to false. That leaves readers with contradictory API guidance.
Verdict
Found: 0 critical, 1 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
![warp-dev-github-integration[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR drops the experimental framing from the Computer Use page, flips the documented default to enabled-for-Oz-cloud-runs, renames Enabling Computer Use → Configuring Computer Use, and rescopes the desktop toggle. I verified the documented behavior against warp-server#13429 (IsComputerUseEnabled now returns inSandbox on the nil branch, getEmptyAgentFormInitialValues / the integration modal default to true) and against the Warp client (cloud_agent_computer_use_enabled is still rendered under the Experimental sub-header on Settings > Agents > Warp Agent, and build_default_spawn_config sends an explicit value so the desktop toggle genuinely does not affect web/API runs) — the prose claims and the desktop scoping are accurate. CI is green, npm run build succeeds locally (350 pages, no errors), the internal link checker reports 0 broken links across 3178 links, and no #enabling-computer-use reference survives anywhere in the workspace, so the heading rename is safe. The blocker is a surface this PR missed.
Concerns
developers/agent-api-openapi.yaml (line 2384) still documents computer_use_enabled as "If not set, defaults to false." That file is the source of truth for the published API reference at docs.warp.dev/api and for docs.warp.dev/openapi.json (src/pages/api.astro, src/pages/openapi.yaml.ts, scripts/generate-openapi-json.mjs all read it), so after this merges the docs site will state the opposite default in two places at once — the Computer Use page will say omitting the field enables computer use while the API reference says it defaults to false. warp-server#13429 updated its own public_api/openapi.yaml, but the docs repo carries a synced copy that this PR did not resync, and the ticket's acceptance criteria explicitly call for the OpenAPI description to no longer read "defaults to false". Resync that file (the repo's sync-openapi-spec skill does this) before merge. It is outside the current diff, so it is raised here rather than inline; it is the same issue the existing oz-for-oss inline comment on line 51 flagged, and it is still unaddressed on this head, so I am not duplicating that thread.
The page now mixes "Computer Use" and "computer use" in adjacent sentences — every line this PR adds uses lowercase while the surrounding page, its headings, and the sibling testing-and-recordings page use "Computer Use". Pick one and apply it to the new prose; the lowest-churn option is matching the page's existing "Computer Use". The repo style linter also flags Configuring Computer Use and the pre-existing How Computer Use works as title case, so if you'd rather go lowercase, do it as a page-wide pass instead of leaving the two styles interleaved.
python3 .agents/skills/style_lint/style_lint.py --changed reports 6 new HARDCODED-VAR hits introduced by this diff (Oz web app on lines 30, 32, 34, 77; oz.warp.dev on line 34; Oz CLI on line 42), plus one on line 35 of computer-use-testing-and-recordings.mdx. Details inline.
Verdict
Found: 1 critical, 2 important, 2 suggestions
Prior concerns still outstanding: the OpenAPI defaults to false contradiction raised on line 51.
Request changes
Review run
https://oz.staging.warp.dev/runs/019fa9f6-a58a-7171-a050-2f4c10e8de61
…, UI labels, casing, desktop toggle note
- Resync developers/agent-api-openapi.yaml from warp-server sibling branch
(computer_use_enabled description now reads 'defaults to true' instead of 'false')
- Extend sync-openapi-spec exclusion policy: add factory, memory tags and
factory-scorer, agent-session-redirect, agent-client-events paths
- Add VARS import to computer-use.mdx; replace all hardcoded 'Oz web app',
'oz.warp.dev', 'Oz CLI' strings with {VARS.WEB_APP}, {VARS.WEB_APP_URL},
{VARS.WARP_AGENT_CLI} (resolves 6 HARDCODED-VAR style-lint hits + 1 in
computer-use-testing-and-recordings.mdx)
- Unify casing: new prose now uses 'Computer Use' consistently throughout
- Fix bolded UI element: **Computer use** → **Enable computer use** in the
Oz web app section bullets (matching shipped checkbox label in warp-server#13429)
- Fix lead-in: 'To disable it' → 'To change it' in Oz web app section
- Add desktop toggle default note: toggle is off by default in released builds
and must be enabled manually
- Fix VARS usage in DemoVideo label in computer-use-testing-and-recordings.mdx
Co-Authored-By: Warp <agent@warp.dev>
There was a problem hiding this comment.
Overview
Re-review of the rework at 07ecba71. All four prior findings are genuinely fixed: the synced computer_use_enabled description now reads "If not set, defaults to true.", the bolded UI element matches the shipped Enable computer use checkbox label in AgentForm.tsx (both default and flat layouts), style_lint.py --changed reports 0 HARDCODED-VAR hits, and the desktop toggle default is documented correctly (cloud_agent_computer_use_enabled defaults to channel().is_dogfood(), so off on released builds). The DemoVideo template-literal substitution renders correctly — the built page emits aria-label="… in the Oz web app with Computer Use". The rework introduced two new blockers, however, one of which has CI red.
Concerns
The {VARS.WEB_APP_URL} substitution on line 36 of computer-use.mdx is placed in a markdown link destination, which MDX does not evaluate. The built page emits href="%7BVARS.WEB_APP_URL%7D" instead of https://oz.warp.dev, and this is exactly why the Build, link-check, audit check is failing on this head with 1 broken internal link. I reproduced it locally and verified the fix in the inline comment: swapping to a JSX anchor renders the real URL, keeps the link checker at 0 broken links, and still builds 350 pages. Worth noting that this is the only place in src/content/docs that puts a VARS expression inside markdown link syntax, and the rework's stated verification ran npm run build and style_lint.py but not check_links.py, which the previous pass had run clean.
The OpenAPI resync has a larger blast radius than the PR describes, and part of it is a public-surface exposure. I checked the "unmerged API surface" worry directly and it does not hold: every one of the 21 newly-added paths already exists on warp-server develop, so this is a stale-spec catch-up (9 → 29 published paths), not publication of the sibling's in-flight work. Only the defaults to true line comes from the unmerged sibling branch. The real problem is that 7 operations explicitly marked x-internal: true server-side are now published in the docs reference and in the generated public/openapi.json: POST /agent/messages, GET /agent/messages/{runId}, POST /agent/messages/{messageId}/read, POST /agent/messages/{messageId}/delivered, GET /agent/events, POST /agent/events/{runId}, and POST /agent/conversations/{conversation_id}/rename. sync-policy.md line 46 blesses this on the grounds that it "matches the pre-existing state of developers/agent-api-openapi.yaml", but that claim is stale — the file on main contains zero x-internal markers, so nothing today publishes these. This PR would ship inter-agent messaging and event-polling internals to customers on docs.warp.dev/api as a side effect of a Computer Use copy change. Either add an x-internal filter to sync_openapi.py (the policy doc already describes that as the alternative) or get explicit sign-off and say so in the PR description.
The page also overstates the new default for self-hosted deployments. After the sibling's rework, IsComputerUseEnabled returns inSandbox on the nil branch, so an omitted computer_use_enabled yields enabled for Warp-hosted sandbox runs and disabled for self-hosted workers. The page states the default unconditionally in two places (the section lede and the API subsection), and the synced OpenAPI text says "If not set, defaults to true." with no qualifier. Self-hosting is a first-class documented deployment mode here (platform/self-hosting/*, platform/runners), so a self-hosted customer reading this page will conclude computer use is on when it is not. The PR body's back-compat note already states the correct behavior; the published page needs to as well. The OpenAPI wording is generated from warp-server, so that half of the fix belongs on warp-server#13429.
Finally, two smaller points. Merge ordering matters: the defaults to true description must not land before warp-server#13429, or the published reference will document a default the API does not yet honor — please note the dependency in the PR description. And the description itself is written as a rework chronicle, with separate "Changes (initial implementation)" and "Changes (rework cycle 1 — addressing review)" sections; please rewrite it as a clean current-state summary of the PR's net effect, and correct the verification section, which currently reads as if checks are passing.
Verdict
Found: 2 critical, 2 important, 1 suggestion
Prior concerns still outstanding: none — all four prior findings are fixed; the blockers below are new.
Request changes
Review run
https://oz.staging.warp.dev/runs/019faa3d-386f-7bac-8df4-196814327338
…ternal OpenAPI ops
- Fix broken JSX variable in markdown link destination (computer-use.mdx:36):
replace [{VARS.WEB_APP}]({VARS.WEB_APP_URL}) with JSX anchor
<a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> so the built page
emits a real href instead of percent-encoded curly braces.
This unbreaks CI (check_links.py was failing on this link).
- Add self-hosted caveat in two places (lines 32 and 53):
the enabled-by-default behavior applies only to Warp-hosted runs;
runs dispatched to self-hosted runners still default to disabled and
require explicit computer_use_enabled: true.
- Add operation-level x-internal filter to sync_openapi.py:
new _filter_internal_operations() + _has_operations() helpers strip
any operation with x-internal: true before the path is included in
the docs subset. This removes 7 internal inter-agent messaging/event
operations (POST /agent/messages, GET /agent/messages/{runId},
POST /agent/messages/{messageId}/read,
POST /agent/messages/{messageId}/delivered, GET /agent/events,
POST /agent/events/{runId},
POST /agent/conversations/{conversation_id}/rename) from
docs.warp.dev/api and public/openapi.json.
- Update sync-policy.md: replace the stale claim that x-internal ops
are kept (which matched old main but not current main) with the
accurate description that they are now filtered out.
- Re-run sync to regenerate developers/agent-api-openapi.yaml with
the new filter applied (22 paths remaining, all $refs resolve).
Co-Authored-By: Warp <agent@warp.dev>
…final wording The cycle-2 commit (d1b4122) resynced developers/agent-api-openapi.yaml from warp-server develop, which still carries "If not set, defaults to false." — undoing the cycle-1 resync from the sibling feature branch. This commit re-syncs from warp-server factory/remote-2358-computer-use-non-experimental at c4837ae, carrying the final hosting-mode-aware wording: "Defaults to true for Warp-hosted runs (when `worker_host` is unset or set to 'warp'). When `worker_host` is set (self-hosted), defaults to false and requires an explicit true to enable computer use and its associated Xvfb sidecar overhead." MERGE ORDER: This docs PR must land AFTER warp-server#13429. Until the sibling merges, a resync from warp-server develop will revert this line to 'defaults to false'. Do not run --mode apply against develop between now and the sibling's merge. Co-Authored-By: Warp <agent@warp.dev>
There was a problem hiding this comment.
Overview
Cycle 2 lands all four claimed fixes: the JSX anchor renders href="https://oz.warp.dev", the 7 internal operations are absent from both generated artifacts, the self-hosted caveat matches IsComputerUseEnabled's inSandbox semantics, and the synced computer_use_enabled description carries warp-server#13429's final worker_host wording. The new x-internal filter is operation-level only, however, and still publishes internal Factory fields to the public API reference.
Concerns
The PR description's change list for sync_openapi.py omits two of the three behavioral changes it makes: it adds factory and memory to EXCLUDED_TAGS and four entries to EXCLUDED_PATHS (/factory/scorers, /factory/scorers/{scorer_id}/results, /agent/sessions/{sessionUuid}/redirect, /agent/runs/{runId}/client-events). Those are the right exclusions and references/sync-policy.md documents them, but a reviewer reading only the description would not know the exclusion policy widened beyond the x-internal filter. Worth one line in the sync_openapi.py bullet.
Verdict
Checks: build ✅ (350 pages) · link-check ✅ (3180 internal links, 0 broken) · style-lint ✅ (4 warnings, all pre-existing or documented false positives) · sync_openapi.py --mode self-test ✅ · --mode diff against warp-server#13429 c4837ae reports "In sync", so the committed spec is exactly reproducible and unedited · CI ✅ on d7402b7 · visual proof n/a (docs-only)
Prior concerns: all three round-2 findings are resolved; the x-internal fix is incomplete at parameter/property granularity.
Found: 0 critical, 1 important, 2 suggestions
Request changes
Review run
https://oz.staging.warp.dev/runs/019faa7f-9ec2-719f-8d46-c2bd43c023ce
…es, add sync-policy note, name worker_host in API docs - sync_openapi.py: add _strip_internal_parameters() and _strip_internal_properties() helpers; extend _filter_internal_operations() to strip x-internal parameters from path-level and operation-level parameters lists; preprocess schemas in transform() to strip x-internal properties before $ref-walking so schemas exclusively referenced via stripped properties (e.g. AgentType) are also pruned; update self-test with parameter/property/InternalOnly pruning cases - developers/agent-api-openapi.yaml: resync from warp-server#13429 branch; factory_uid param on GET /agent/identities and factory_uid/agent_type properties on CreateAgentRequest/UpdateAgentRequest/AgentResponse removed; AgentType enum schema dropped via $ref pruning - references/sync-policy.md: document parameter/property x-internal stripping; add durable merge-ordering note (delete once warp-server#13429 lands) - computer-use.mdx: name worker_host as the actual switch in the API section Co-Authored-By: Warp <agent@warp.dev>
There was a problem hiding this comment.
Overview
Docs-side of the computer-use default flip: experimental framing removed, the new Warp-hosted default documented with an explicit self-hosted caveat, and the OpenAPI sync taught to strip x-internal at operation, parameter, and property level. All three cycle-3 claims verified directly against the artifacts; one non-blocking rendering nit remains.
Concerns
The ### {VARS.WEB_APP} heading (inline comment on computer-use.mdx:34) is the only remaining item. It is cosmetic and does not block merge, but it is a one-click suggestion worth applying before you merge.
Independent verification of the cycle-3 claims, for the record: developers/agent-api-openapi.yaml and the build-generated public/openapi.json both contain zero x-internal markers and no factory_uid / agent_type / AgentType; the 61 x-internal operations in the source spec are all absent from the output. No over-pruning — every property dropped from a surviving schema carried an explicit x-internal: true (5 total), no required entry references a stripped property, and every $ref in the output resolves. AgentType is referenced in the source only from the three stripped agent_type properties, so its pruning is correct rather than collateral. Against origin/main the only path this resync removes is /harness-support/transcript, an internal worker-to-server endpoint, so the widened EXCLUDED_TAGS / EXCLUDED_PATHS do not withdraw any published customer surface.
The worker_host prose matches the server contract after the sibling's cycle-3 switch to IsWarpHosted(): ResolveWorkerKindFromHost("") and "warp" route to AnyWarpHosted, and the public spec's own worker_host description states exactly the same unset-or-"warp" rule. sync-policy.md documents the parameter/property stripping and carries a merge-ordering note explicitly marked deletable once warp-server#13429 lands.
Verdict
Checks: build ✅ · link check ✅ (3179 internal links, 0 broken) · sync_openapi.py --mode diff against sibling head c15db7b3 ✅ ("In sync") · self-test ✅ · style lint ✅ (4 warnings, all pre-existing or defensible) · CI ✅ (6/6 green on 29af807) · visual proof n/a (docs-only)
Prior concerns: none remain — all 10 threads from the three earlier passes are resolved and verified fixed at this head.
Found: 0 critical, 0 important, 1 non-blocking suggestion
Approve
Review run
https://oz.staging.warp.dev/runs/019faac2-05d4-785e-bf62-4d1a30e73146
| Computer Use is **enabled by default** for Warp-hosted Oz cloud runs. When starting a run from the {VARS.WEB_APP}, the Computer Use checkbox is pre-selected. When calling the API without specifying `computer_use_enabled`, Computer Use is on for Warp-hosted runs; runs dispatched to [self-hosted runners](/platform/runners/) still require an explicit `computer_use_enabled: true`. You can disable or explicitly control it through the following entry points: | ||
|
|
||
| Computer Use is **opt-in** and disabled by default. You can enable it through several entry points: | ||
| ### {VARS.WEB_APP} |
There was a problem hiding this comment.
💡 [SUGGESTION] Non-blocking, but worth fixing before merge. Starlight builds the “On this page” table of contents from the raw heading text, so this MDX expression is not evaluated there: the built page renders the literal string VARS.WEB_APP in both the desktop and mobile ToC, and the heading anchor becomes #varsweb_app instead of a readable slug. The <h3> body text itself resolves correctly to “Oz web app”, so only the nav label and anchor are affected. This is the only heading in src/content/docs/ that uses a {VARS.*} expression, and the only page in the built site whose ToC leaks a literal VARS.* string — matching the repo-wide precedent of plain-text headings avoids it.
| ### {VARS.WEB_APP} | |
| ### Oz web app |
1 participant
Summary
Computer use in Oz cloud runs is no longer experimental and is now enabled by default for Warp-hosted runs. This PR updates the docs to reflect the new defaults, adds an x-internal operation filter to the OpenAPI sync, and qualifies the self-hosted behavior.
Changes
agent-platform/capabilities/computer-use.mdxworker_hostunset or "warp"); runs dispatched to self-hosted runners default to disabled and require explicitcomputer_use_enabled: trueworker_hostas the actual switch so callers can predict the behavior from their own request bodyOz web app,oz.warp.dev,Oz CLIstrings with VARS variables; fix broken JSX variable in markdown link destination (use<a href={VARS.WEB_APP_URL}>not]({VARS.WEB_APP_URL}))AgentForm.tsx)agent-platform/capabilities/computer-use-testing-and-recordings.mdx#enabling-computer-use→#configuring-computer-useOz web appoccurrences with{VARS.WEB_APP}developers/agent-api-openapi.yamlc4837ae).computer_use_enableddescription now reads the final hosting-mode-aware wording: "Defaults to true for Warp-hosted runs (whenworker_hostis unset or set to 'warp'). Whenworker_hostis set (self-hosted), defaults to false and requires an explicit true..."x-internal: true(7 inter-agent messaging/event operations excluded); (2) parameters withx-internal: truestripped from path-level and operation-levelparameterslists; (3) schema properties withx-internal: truestripped frompropertiesmaps —factory_uidonGET /agent/identities, andfactory_uid/agent_typeonCreateAgentRequest/UpdateAgentRequest/AgentResponseare all absent;AgentTypeenum pruned via $ref reachabilitymodel_id/reasoning_level,RunSourceTypeJIRA, agent artifact/conversation/run endpoints).agents/skills/sync-openapi-spec/scripts/sync_openapi.py_HTTP_METHODSconstant,_filter_internal_operations(), and_has_operations()helpers (operation-level x-internal filter)_strip_internal_parameters()and_strip_internal_properties()helpers for recursive field-level stripping_filter_internal_operations()now also strips x-internal entries from path-level and operation-levelparametersliststransform()preprocesses schemas to strip x-internal properties before $ref-walking; schemas exclusively referenced via stripped properties (e.g. an internal enum) are automatically pruned outfactoryandmemorytoEXCLUDED_TAGS(internal agent-orchestration and memory-stores APIs)EXCLUDED_PATHS:/factory/scorers,/factory/scorers/{scorer_id}/results,/agent/sessions/{sessionUuid}/redirect,/agent/runs/{runId}/client-events.agents/skills/sync-openapi-spec/references/sync-policy.mdfactory_uid,agent_type)Verification
npm run build— 350 pages, no errors, OpenAPI JSON generatedcheck_links.py --internal-only— 3179 internal links checked, 0 broken linksstyle_lint.py --changed— 4 warnings, all pre-existing or documented false positives (2 HEADER-CASE on "Computer Use" proper feature name; 1 PRODUCT-CASING and 1 UNRECOGNIZED-TERM in unchanged files)sync_openapi.py --mode self-test— OK (includes new parameter/property stripping test cases)sync_openapi.py --mode diffagainst warp-server#13429 branch — "In sync. No changes needed."x-internal,AgentType,factory_uid, oragent_typestrings indevelopers/agent-api-openapi.yaml; all $refs resolve29af807)Back-compat: Callers sending explicit
computer_use_enabled: falseare unaffected. Self-hosted workers (worker_hostset) default to disabled. The desktop Warp app toggle remains off by default in released builds and is documented as desktop-client-only.Rework changes (cycle 3)
sync_openapi.pyto stripx-internal: trueat parameter and property level, not just operation level. Added_strip_internal_parameters()and_strip_internal_properties()helpers; extended_filter_internal_operations()to handle path-level and operation-levelparameterslists; added a schema-preprocessing pass intransform()so x-internal properties are stripped before $ref-walking (causing exclusively-stripped-property-referenced schemas likeAgentTypeto be naturally pruned). Regenerated spec:factory_uidparam onGET /agent/identitiesabsent,factory_uid/agent_typeproperties onCreateAgentRequest/UpdateAgentRequest/AgentResponseabsent,AgentTypeenum absent. Self-test extended with parameter/property/InternalOnly pruning assertions.references/sync-policy.mdwhich the sync skill reads before running.worker_host(implemented, resolved): Updated the API subsection (line 53) to nameworker_hostas the actual switch ("whenworker_hostis unset or set to"warp", computer use defaults to enabled; whenworker_hostis set to any other value...") so an API caller can predict the behavior from their own request body.sync_openapi.pybullet to explicitly list the two newEXCLUDED_TAGSadditions (factory,memory) and four newEXCLUDED_PATHSthat the PR description had omitted.Originating thread: Slack
Conversation: https://staging.warp.dev/conversation/dc8a41ca-5eca-4010-9375-99e2d20e350a
Run: https://oz.staging.warp.dev/runs/019faa9e-b652-71af-bc8a-b145efe6bd04
This PR was generated with Oz.