Connectors
The webtop connector kind: how a virtual desktop's container filesystem joins the platform's URI filesystem.
machine-core contributes one source connector, kind webtop, over the standard
connector port. It backs every machine source, so
the container filesystem joins brain-core's
URI filesystem like any other source.
Declaration
The manifest declares the connector with the URL scheme machine, default scope
user, and a scope selectable across user, project and agent. Every source
created on it persists under its own slug, and the slug is the URI scheme: the
user-scoped source machine-ops lists its root as machine-ops://, and
machine-ops:///config/notes.md addresses /config/notes.md inside that
container. All scoped slugs share one connector implementation; the slug is the
identity.
The connector advertises fifteen capabilities of the port — list, read,
rawRead, write, delete, move, exec, execDetached, scanDelta, walk,
count, peekCount, scanContent, subscribeEvents and resolveOsUri.
peekCount never makes the trip to the container: it always answers "no cheap
estimate", so callers fall back to a real count. Its config schema is closed and
empty: a machine source needs no connection settings, because the binding to the
live container is resolved at runtime from the active session.
No host path inside the sandbox
resolveOsUri on a machine source returns the container-internal path:
machine-ops:///config/x.md resolves to /config/x.md. This is deliberate. The
sandbox has no host-side path to expose, so the connector neither fabricates a host
path nor reports the location as unresolvable. Host/container path translation only
applies to connector kinds that straddle both environments (a host folder on this
server); a machine source never participates in it.
Project-scoped, fail-closed
The connector is constructed once per project and captures that project at
construction, so two projects that share a slug name can never cross-resolve each
other's container filesystems. When no live session is registered for the slug,
filesystem calls fail with a typed "no running machine session" error (or return
empty for list-class calls), so fs_* tools surface the missing prerequisite instead
of succeeding against a placeholder. Filesystem reads acquire no startup authority.
Connector execution (Webtop shell) is separate: it requires the real session and may
start the machine after the scope, feature and lifecycle checks.
The Webtop filesystem read returns original bytes within the configured read cap, plus a UTF-8 preview or a binary marker; oversized binary reads never expose a partial file as a complete attachment.