Skip to content

refactor(cos): delegate desktop and computer to the createos CLI - #60

Draft
pratikbin wants to merge 1 commit into
mainfrom
feat/cos-delegate-computer-to-cli
Draft

pratikbin wants to merge 1 commit into
mainfrom
feat/cos-delegate-computer-to-cli

Conversation

@pratikbin

Copy link
Copy Markdown
Contributor

Blocked on NodeOps-app/createos-cli#94. Do not merge until that ships in a released CLI. Merging earlier breaks desktop and computer-use for every plugin user, because createos sandbox computer does not exist yet.

What

Deletes the REST layer cos carried for desktop and computer, and shells out to createos sandbox desktop / createos sandbox computer like every other verb.

-387 / +103. Gone: api(), api_auth(), api_check(), desktop_wait().

Why

That layer was the single place cos bypassed the CLI, and it cost a second implementation of things the CLI already knew — its own auth precedence, its own error-code map, its own readiness poll. It also carried a false premise: a comment asserting the CLI does not read CREATEOS_API_KEY, which it has all along (cmd/root/root.go:77). The auth fallback ordering rested on that.

The same code now serves pi-extension, opencode-plugin and herdr-plugin, which could not do computer-use at all, because they only shell out. This is ADR-0001's direction: fold the engine into the CLI, keep the plugin thin.

What stays in cos

Only what the CLI cannot know:

  • Project-box resolution — which box belongs to this directory, and creating one on desktop:1 when there is none. The CLI is stateless by design.
  • The rootfs guard — the CLI refuses a non-desktop box too, but tells you to create a new sandbox. For a project box that is wrong: there is one per directory, so the fix is cos down && cos desktop.

Compatibility

  • cos computer screenshot -o file still works. The CLI spells it --out, because -o is its global output-format flag, so cos translates rather than breaking callers.
  • cos probes for sandbox computer and tells the user to upgrade, instead of failing with a bare "unknown command".
  • Both copies updated through scripts/sync-shared.sh; --check passes (9 copies in sync).

One behavior found while testing

cos resume now prints a hint to re-run cos desktop on a box that had one. A resumed desktop answers reads (screen, screenshot) before its input stack is back, so click and move return 409 desktop_unavailable for a moment after the readiness probe already succeeds. Confirmed server-side: computer raw POST mouse/click with a hand-written body failed identically while cursor returned correct coordinates, and everything passed on retry.

This means /computer/screen is not a sufficient readiness probe after a resume. Worth a follow-up on the fc side; the hint is the cheap mitigation.

Verification

Ran end-to-end against a live box with the CLI from #94 (COS_CLI=), then destroyed it:

  • cos desktop created the desktop:1 project box and returned a working noVNC URL with expiry
  • computer screen 1280×800, open, key ctrl l, type (multi-word joined correctly), click, screenshot via the legacy -o (48.9 KB written)
  • paused-box guard fired correctly
  • old-CLI probe: a stub without sandbox computer produced the upgrade message, not a stack trace
  • bash -n clean on both copies

Docs updated

  • SKILL.md Pattern D rewritten: says both verbs are CLI wrappers, points at createos sandbox computer --help for unwrapped ops (clipboard, window manipulation, screen resize), notes a box addressed by name needs no project state, and warns that an old CLI has no sandbox computer.
  • README.md: the note claiming these are the only verbs calling REST directly is now accurate.

The CLI grew `sandbox desktop` and `sandbox computer`, so the REST layer
this driver carried for them has no reason to exist. Delete api(),
api_auth(), api_check() and desktop_wait(), and shell out like every
other verb.

That layer was the one place cos bypassed the CLI, and the cost of it
was a second implementation of things the CLI already knew: its own auth
precedence, its own error-code map, its own readiness poll. It also held
a false premise — a comment claiming the CLI does not read
CREATEOS_API_KEY, which it has (cmd/root/root.go). The same code now
serves pi, opencode and herdr, which could not do computer-use at all.

cos keeps what the CLI cannot know: which box belongs to this project,
and creating one on a desktop image when there is none. The rootfs guard
stays too, because the CLI tells you to create a new sandbox, and for a
project box the fix is to replace the one you have.

Two details preserved for callers:

- `cos computer screenshot -o file` still works. The CLI spells it
  --out, since -o is its global output-format flag, so cos translates.
- `cos resume` now says to re-run `cos desktop` on a box that had one. A
  resumed desktop answers reads before its input stack is back, so a
  click can 409 for a moment after the screen route already succeeds.

Requires a createos CLI carrying those commands. cos probes for them and
tells the user to upgrade rather than failing with "unknown command".

Blocked on NodeOps-app/createos-cli#94.
@pratikbin
pratikbin force-pushed the feat/cos-delegate-computer-to-cli branch from 84c14ca to d20d764 Compare September 16, 2026 08:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant