feat(sandbox): add first-class session and conversation lifecycle support

[rohancmr]

Problem Statement

Some platforms run interactive AI-agent workflows where a sandbox may host a logical conversation, task, or session over time.

Today, OpenShell primarily exposes the sandbox as the main execution object. A caller can create a sandbox and execute work against that sandbox, but OpenShell does not have a first-class concept of a logical session or conversation inside the sandbox.

For interactive agent systems, the platform often needs to track:

• which conversation is assigned to which sandbox,
• who owns that conversation,
• when the conversation should expire,
• whether the sandbox is still safe to use for that conversation,
• how to route follow-up requests back to the same sandbox,
• how to cancel or release one conversation,
• and how to audit activity by conversation rather than only by sandbox.

Without this, every platform must build its own external mapping such as:

conversation_id -> sandbox_id

That mapping is important for resume, cancel, logs, audit, scheduled/background work, and cleanup.

Proposed Design

Add a first-class session or conversation abstraction associated with a sandbox.

Conceptually:

Sandbox
  └── Session / Conversation
        ├── owner
        ├── tenant/project metadata
        ├── TTL
        ├── status
        ├── policy/provider context
        ├── audit metadata
        └── lifecycle operations

Possible API shape:

sandbox_id: sandbox-abc123
session_id: conversation-456
owner: user@example.com
tenant: nvbugs
ttl_seconds: 3600
metadata:
  workflow: code-analysis
  request_id: req-abc123

OpenShell would persist the mapping and allow future operations to reference the session:

CreateSandboxSession
GetSandboxSession
ListSandboxSessions
RefreshSandboxSession
CancelSandboxSession
ReleaseSandboxSession

Execution, file, log, and provider operations could optionally include session_id so audit and lifecycle tracking are tied to the logical workflow, not only the sandbox.

This issue is intended as a design discussion starter. The exact API shape and whether this belongs as an issue, RFC, or part of a broader lifecycle design should be decided by OpenShell maintainers.

Required Behavior

OpenShell should support:

• Creating a logical session/conversation for an existing sandbox.
• Persisting session_id -> sandbox_id mapping.
• Returning the same sandbox for follow-up operations on the same session.
• Tracking session owner, tenant/project metadata, TTL, status, and audit fields.
• Releasing or expiring a session independently from deleting the sandbox.
• Cancelling work associated with a session.
• Listing sessions for a sandbox, subject to authorization.
• Emitting lifecycle events for session create, active, idle, cancelled, expired, released, and failed.

Security Requirements

• A caller should only see or operate on sessions it is authorized to access.
• Session metadata must not allow one tenant/user to discover another tenant/user's sessions.
• Session ownership must be enforced server-side.
• If multiple sessions are allowed in one sandbox, OpenShell must only allow that when policy permits it.
• Multi-session use should be restricted to compatible sessions, for example same tenant, same policy fingerprint, same provider scope, or an explicitly approved packing profile.
• Credentials and provider context from one session must not leak into another session.
• Session cleanup should remove or invalidate request/session-scoped credentials and runtime state associated with that session.

Why This Is Needed

Interactive AI-agent systems often need continuity.

A follow-up request should return to the same sandbox that contains the conversation workspace, files, background jobs, and execution context. Scheduled or background tasks also need to know which sandbox owns the session.

Without a first-class session abstraction, platforms must maintain this mapping outside OpenShell. That makes authorization, audit, cleanup, and failure recovery harder.

A session abstraction would let OpenShell remain the sandbox execution plane while giving platforms a clean way to manage long-running or resumable workflows.

Optional Future Capability: Controlled Session Packing

Some platforms may want to run more than one compatible session in the same sandbox for density and cost reasons.

This should be an explicit policy-controlled mode, not the default.

Example constraints:

• same tenant,
• same owner or approved shared owner group,
• same policy fingerprint,
• same provider/credential scope,
• same network access profile,
• bounded max sessions per sandbox.

If those constraints are not satisfied, OpenShell should require a separate sandbox.

Alternatives Considered

Track conversation-to-sandbox mapping only in the external platform

This works, but it pushes important lifecycle and audit state outside OpenShell. It also makes cleanup and failure recovery harder when gateway state, sandbox state, and platform state drift.

Create one sandbox per conversation

This is simple and secure, but it can be expensive for high-volume interactive workloads and does not provide a clean abstraction for resumable sessions.

Reuse a sandbox without a session model

This is risky because ownership, audit, TTL, credentials, and cleanup are not tied to a logical workflow.

Agent Investigation

I reviewed the current OpenShell issue list and did not find a dedicated feature request for first-class sandbox sessions, conversation pinning, or multi-session tracking.

Related work exists around provider credentials, warm pools, lifecycle management, and gateway state, but not a dedicated session/conversation abstraction.

Checklist

• I have searched existing issues for related session/conversation requests.
• This is a design proposal, not only a request to build a feature.

[johntmyers]

Without this, every platform must build its own external mapping such as...

I think this is the point of OpenShell, it should be built upon. Otherwise we start to add bespoke features that may not work well for users. I would first suggest building out some workloads and seeing what gaps there are on in OpenShell's extendability. Our goal is to provider hooks and middleware in the right surface areas to allow arbitrary extendability.

This feels a bit abstract to me and more like an application that should be built on top of OpenShell.