Expose native agentOS hooks/actions for unsupported core AgentOs surfaces

[NathanFlurry]

Problem

The native RivetKit agentOS() actor supports a serializable subset of core AgentOs, plus a few actor-level hooks/events. Some core surfaces still have no native RivetKit equivalent. Users who need them must either drop down to core AgentOs or build a custom JS actor wrapper, which means giving up the native actor package path.

This issue tracks the truly unsupported areas that should either become native actor actions, config hooks, or documented actor events.

Unsupported / needs RivetKit surface

Runtime filesystem mounting

• mountFs(path, driver, options?)
• unmountFs(path)

Why: useful for mounting app/session/workspace storage after VM boot. JS callback-backed drivers cannot cross into native VM config, so the native actor needs either a hook/action pattern or a native/plugin-backed alternative.

Shell / terminal lifecycle

• openShell()
• writeShell()
• resizeShell()
• closeShell()
• connectTerminal()

Why: core AgentOS supports interactive shell/PTY workflows, but the native actor dispatcher does not currently expose matching actions. shellData exists as an event type, but the lifecycle actions are missing.

Session control and raw ACP access

• cancelSession()
• respondPermission()
• setSessionMode() / getSessionModes()
• setSessionModel()
• setSessionThoughtLevel()
• getSessionConfigOptions()
• getSessionCapabilities()
• getSessionAgentInfo()
• rawSessionSend() / rawSend()

Why: these are core session-control APIs used for richer agent UIs and ACP integrations. Native actor users currently get create/prompt/close/persisted-events, but not the full control plane.

Session creation MCP config

• CreateSessionOptions.mcpServers

Why: core supports attaching MCP servers per session. The native actor DTO only carries cwd/env/instruction fields today, so MCP-enabled sessions cannot be configured through native RivetKit AgentOS.

Root filesystem snapshot/export

• snapshotRootFilesystem()

Why: useful for debugging, persistence export, tests, and workspace capture. No native actor action currently mirrors it.

Agent/session listing parity

• listSessions()
• listAgents()

Why: core exposes live sessions and registered agent metadata. Native actor exposes persisted sessions, but not the same live/session registry or agent registry information.

Exec/process option parity

• execArgv()
• full exec / spawn option objects

Why: native actor currently exposes narrower serializable process actions. Some core options and argv-style execution are not mirrored. Callback stream options should map to actor events rather than JS callbacks.

Cron parity

• callback cron actions
• custom scheduleDriver

Why: these are callback/object-based in core and cannot be serialized into native config. If needed in RivetKit, they need actor-level hooks or a documented replacement shape.

Host toolkits

• toolKits

Why: core host tools use JS execute callbacks and schemas. Native actor config cannot serialize those into the VM. If supported, this likely needs an actor-level host-tool bridge/hook rather than raw config serialization.

Agent stderr hook

• onAgentStderr

Why: core accepts a direct JS callback. Native actor should expose this through an actor hook or event if stderr streaming is expected for apps.

Notes

This is not asking to serialize arbitrary JS callbacks through AgentOsConfigJson. The likely split is:

• serializable things become native actor actions/DTO fields;
• stream/callback things become actor events or config hooks;
• live JS-object features need explicit actor-layer bridges or documented unsupported status.

Related: custom user-defined actions are tracked separately in #1522.