WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

internal/sandbox/capabilities.go

@@ -0,0 +1,124 @@
+// Package sandbox: session-scoped capability interfaces.
+//
+// The Sandbox / Manager pair intentionally hides provider identity (Cube,
+// E2B, Docker) from the application layer. Higher layers should never
+// branch on Manager.GetType() to decide whether a feature is supported —
+// that couples them to a specific backend.
+//
+// Instead, session-scoped features (shell execution, per-session file
+// inspection, attachment staging) are advertised via the capability
+// interfaces below. A manager may satisfy the underlying methods yet still
+// return nil from the accessors on SessionCapabilityProvider when the
+// current runtime configuration cannot honour that capability.
+package sandbox
+
+import (
+	"context"
+	"time"
+)
+
+// SessionShellExecutor executes ad-hoc shell commands inside a session-
+// scoped remote sandbox. SessionBoundManager surfaces it while Cube, E2B,
+// or Docker is active.
+type SessionShellExecutor interface {
+	ExecShellCommand(
+		ctx context.Context,
+		sessionID string,
+		command string,
+		workDir string,
+		timeout time.Duration,
+		env map[string]string,
+	) (*ExecuteResult, error)
+}
+
+// SessionFileStore is the effective per-session filesystem view a manager
+// offers callers that need to inspect, stage, or clean up files inside the
+// session's remote sandbox. It is intentionally provider-neutral: entries
+// use RemoteDirEntry / RemoteStatEntry, so E2B and Cube can implement it
+// without touching the caller.
+type SessionFileStore interface {
+	// EnsureSessionDir creates dir in the session's live sandbox. Silent
+	// no-op when no sandbox is bound yet; the next Execute call will
+	// materialise the directory during script upload.
+	EnsureSessionDir(ctx context.Context, sessionID, dir string) error
+
+	// ListSessionFiles walks dir recursively and returns file entries.
+	// Returns nil (no error) when the session has no live sandbox so
+	// callers can treat "no sandbox" and "empty output" uniformly.
+	ListSessionFiles(ctx context.Context, sessionID, dir string) ([]RemoteDirEntry, error)
+
+	// StatSessionFile returns metadata for a single file. Errors when the
+	// session has no bound sandbox — callers of this method already hold a
+	// path from a prior ListSessionFiles call.
+	StatSessionFile(ctx context.Context, sessionID, path string) (*RemoteStatEntry, error)
+
+	// ReadSessionFile downloads a file's contents. Same "no sandbox
+	// bound" contract as StatSessionFile.
+	ReadSessionFile(ctx context.Context, sessionID, path string) ([]byte, error)
+
+	// WriteSessionInputFile writes a durable attachment path into the
+	// session's remote sandbox, provisioning the sandbox on first call.
+	WriteSessionInputFile(ctx context.Context, sessionID, filePath string, content []byte) error
+
+	// WriteSessionWorkspaceFile writes a model-authored file under
+	// /workspace. /workspace/input stays read-only (attachments); everything
+	// else under /workspace is accepted so generated scripts do not have to
+	// travel through shell_exec heredocs.
+	WriteSessionWorkspaceFile(ctx context.Context, sessionID, filePath string, content []byte) error
+
+	// RemoveSessionInputPath deletes a staged attachment. No-op when the
+	// session has no live sandbox.
+	RemoveSessionInputPath(ctx context.Context, sessionID, targetPath string) error
+}
+
+// SessionCapabilityProvider is implemented by managers that MAY offer
+// session-scoped capabilities. Accessors return nil when the current
+// runtime configuration cannot support that capability. Application code
+// should gate feature registration on non-nil accessor returns.
+type SessionCapabilityProvider interface {
+	SessionShellExecutor() SessionShellExecutor
+	SessionFileStore() SessionFileStore
+}
+
+// SessionInstallShellExecutor runs install/maintenance shell commands, which
+// need root and the skills image root. It is a separate interface from
+// SessionShellExecutor so the privilege is something a caller must ask for by
+// name: ordinary chat sessions keep the non-root, /workspace-only contract.
+type SessionInstallShellExecutor interface {
+	ExecShellCommandWithOptions(
+		ctx context.Context,
+		sessionID string,
+		command string,
+		opts ShellExecOptions,
+	) (*ExecuteResult, error)
+}
+
+// SessionFileReader reads one file out of a session's sandbox. It is the
+// single-method slice of SessionFileStore that callers which only ever read
+// need, so a manager offering just this much is enough for them.
+type SessionFileReader interface {
+	ReadSessionFile(ctx context.Context, sessionID, path string) ([]byte, error)
+}
+
+// SessionDestroyer releases the remote sandbox bound to a session, leaving the
+// session record itself alone. Like RemoteSnapshotManager it is an optional
+// capability: stateless backends have nothing to release.
+type SessionDestroyer interface {
+	DestroySession(ctx context.Context, sessionID string) error
+}
+
+// SessionInstallCapabilityProvider is implemented by managers that can run
+// install-mode shell commands. Like the other accessors it returns nil when
+// the current runtime cannot honour the capability.
+type SessionInstallCapabilityProvider interface {
+	SessionInstallShellExecutor() SessionInstallShellExecutor
+}
+
+// SessionTurnHolder marks the start and end of one chat turn on a session's
+// sandbox. While the turn is open, a stale image mark waits: the first
+// resolve of the turn may rebuild, later resolves of the same turn keep the
+// sandbox so /workspace scratch and in-flight execs survive an admin install.
+type SessionTurnHolder interface {
+	BeginSessionTurn(ctx context.Context, sessionID string) error
+	EndSessionTurn(ctx context.Context, sessionID string) error
+}