Documentation
¶
Overview ¶
Package sessionworkspace stores a per-session "workspace": a set of ephemeral connector instances cloned from a base module (httprest, custom API defs, …). It backs the wick_session_workspace MCP tool and the session Config tab.
A session instance is a throwaway clone: it has its own id, a base module key, a label, and a config map — exactly the configurable fields of the base module, filled in for this session only. It shows up in wick_list / wick_get / wick_execute only when the caller passes the owning session_id, behaving like a brand-new connector that lives and dies with the session dir.
Secret config values are stored as wick_cenc_ MASTER tokens (system decryptable only) — callers encrypt BEFORE Set/Add; this package never sees or persists plaintext secrets. The whole file dies with the session, which is the intended instance lifetime.
Index ¶
- Constants
- func IsInstanceID(id string) bool
- func NewInstanceID() string
- func Remove(layout agentconfig.Layout, sessionID, instanceID string) (bool, error)
- func SetConfig(layout agentconfig.Layout, sessionID, instanceID string, ...) error
- func SetLabel(layout agentconfig.Layout, sessionID, instanceID, label string) error
- func SetReapNotify(fn func(sessionID string, tombs []Tombstone))
- func StartSweeper(layout agentconfig.Layout)
- type Instance
- type Tombstone
- type Workspace
Constants ¶
const IDPrefix = "sw_"
IDPrefix marks a connector id as a session-workspace instance, so MCP handlers can route it to the workspace resolver instead of the DB.
const IdleGrace = 10 * time.Minute
IdleGrace is how long a session may sit idle (no running/queued subprocess, no activity) before its connector instances are reaped. Instances are throwaway credential clones that exist only for active work on a session; once the session goes quiet, holding their config (secrets and all) is pure exposure with no benefit, so we drop them. A short grace lets a user step away from a chat and come back without losing their setup. Tune here.
Variables ¶
This section is empty.
Functions ¶
func IsInstanceID ¶
IsInstanceID reports whether an id refers to a session-workspace instance (vs a real DB connector row).
func Remove ¶
func Remove(layout agentconfig.Layout, sessionID, instanceID string) (bool, error)
Remove deletes an instance. ok=false when it wasn't there.
func SetConfig ¶
func SetConfig(layout agentconfig.Layout, sessionID, instanceID string, values map[string]string) error
SetConfig merges config values into an instance and persists. Keys not present in values are kept. Returns os.ErrNotExist-wrapped error when the instance is gone.
func SetLabel ¶ added in v0.18.0
func SetLabel(layout agentconfig.Layout, sessionID, instanceID, label string) error
SetLabel renames an instance. Returns an os.ErrNotExist-wrapped error when the instance is gone. Empty label is rejected — the caller should fall back to a default before calling.
func SetReapNotify ¶ added in v0.32.0
SetReapNotify installs the post-reap notification hook. Call once at boot, before StartSweeper. Passing nil disables notification.
func StartSweeper ¶ added in v0.32.0
func StartSweeper(layout agentconfig.Layout)
StartSweeper does a single scan at boot and, if any instances remain, leaves the reaper running. Called once from the web server so a process restart still reaps instances whose sessions went idle while it was down. When every workspace is already empty it spawns nothing.
Types ¶
type Instance ¶
type Instance struct {
ID string `json:"id"` // "sw_<uuid>"
BaseKey string `json:"base_key"` // module key it clones (e.g. "httprest")
Label string `json:"label"`
// Config holds the instance's config field values. Secret fields are
// wick_cenc_ master tokens; non-secret fields are plaintext.
Config map[string]string `json:"config"`
// CreatedBy is "ai" (added via the MCP tool) or "user" (added in the
// Config tab) — drives the "agent added this, please fill it" notice.
CreatedBy string `json:"created_by,omitempty"`
CreatedAt string `json:"created_at,omitempty"`
}
Instance is one ephemeral connector clone scoped to a session.
func Add ¶
Add appends a new instance and persists it. The id is minted here if empty. Returns the stored instance (with its final id).
func List ¶
func List(layout agentconfig.Layout, sessionID string) ([]Instance, error)
List returns all live instances in a session, in stored order. Expired instances are hidden here even before the sweeper reclaims their file — an expired instance is dead, so it must not appear or be usable in the gap between expiry and physical deletion.
type Tombstone ¶ added in v0.32.0
type Tombstone struct {
Label string `json:"label"`
BaseKey string `json:"base_key"`
DeletedAt string `json:"deleted_at"` // RFC3339
Reason string `json:"reason,omitempty"` // e.g. "session idle"
}
Tombstone is the trace left behind when an instance is auto-reaped for session inactivity. It carries NO config — the whole point of reaping is that the config (secrets and all) is gone. It exists so the Config tab and the agent can say "this connector was here, it was deleted, re-create it if you still need it" instead of the instance silently vanishing.
func Tombstones ¶ added in v0.32.0
func Tombstones(layout agentconfig.Layout, sessionID string) ([]Tombstone, error)
Tombstones returns the traces of instances auto-reaped for inactivity in a session, so the UI/agent can show "was here, deleted, re-create" notices.
type Workspace ¶
type Workspace struct {
Instances []Instance `json:"instances"`
Tombstones []Tombstone `json:"tombstones,omitempty"`
}
Workspace is the full per-session document. Tombstones records instances auto-reaped for inactivity so the UI can surface a "deleted — re-create" notice; they hold no config.
Source Files