colab #

the colab extension (requires python and remote) manages Google Colab runtimes from the kernel and reaches one through remote.

• sign-in: /login colab stores a Google account under accounts["google-colab"] in creds.json (access, refresh, expires, email). the OAuth mechanics (code exchange, userinfo email, locked refresh) are albedo_google_oauth.erl's, shared with antigravity; albedo_colab_auth.erl is the colab client and account choice: the selected account, else the first.
• tokens stay in the daemon: the kernel never reads creds.json. the colab.account host route (extension.gleam) answers {access, email} with the token refreshed and saved under the credential lock, or a refusal that colab.py raises as ColabError. every API call asks again, so a long session outlives the hour a token lives.
• runtimes: colab.instances(), status(), launch() and stop() call the /tun/m/* endpoints with the XSRF handshake. an instance is a ColabInstance record with connect() and stop() methods.
• connect: colab.connect(vm) takes a fresh listing (the runtime proxy token expires), registers an ssh alias colab-<id> and returns remote.connect() on it. the alias's ProxyCommand is python -m albedo_plugins.ws, which bridges stdio to wss://<proxy>/colab/ssh; the proxy url and the public key header reach it as ALBEDO_WS_URL and ALBEDO_WS_HEADERS in its environment. nothing is written to ~/.ssh/config. a missing ssh public key (~/.ssh/id_ed25519.pub, id_ecdsa.pub, or ssh_key=) is an error before anything connects. stop() drops the alias; it does not close a connection already open on it.
• occupied ssh slot: only after remote.connect() fails, a bounded websocket handshake probe checks for HTTP 429 with already-active-session. this raises ColabSshSessionError (a ColabError, status=429). unrelated refusals and probe failures preserve the original RemoteError; successful connects cost no extra request. a previously held server-side session may survive a bridge restart. retrying does not release it. stop()/unassign is the only forceful reset and destroys the VM; never do that to recover files from a live job.
• HTTP recovery: await colab.runtime_status(vm) reads Jupyter /api/status; await colab.contents(vm, "content") lists a directory; await colab.contents(vm, path, content=False) reads metadata (including size); await colab.read(vm, path) returns a text file in memory; await colab.pull(vm, path, local, resume=True) streams /files/<path> to disk in 1 MiB chunks and returns its local Path. these read-only routes refresh the runtime proxy token and work independently of ssh. paths are relative to Jupyter's root, not /content. partial downloads remain for retry; resume assumes unchanged remote content, so use resume=False for mutable files. an ignored Range restarts rather than appending; invalid ranges and HTTP 416 fail instead of claiming completeness. runtime HTTP errors omit credential URLs.
• tests: test/harness/colab_plugin_test.py (the plugin against a faked HTTP layer), ws_test.py (frames, and the bridge in a real subprocess) and google_oauth_test.gleam (the refresh against a local token endpoint).