workspace.*

workspace.* is the runtime surface over the AgentEnvStore (SQLite-backed). Five core methods are wired in register_workspace_handlers (src/bin/aleph-server/commands/start/builder/handlers/settings.rs:6-88); the channel-binding surface lives in the same module, since the bind / unbind seam is shared with the agent_switch builtin tool.

The store model is one workspace per agent, many channels per agent. A workspace is a logical isolation boundary — it carries the agent's profile, project root, and binding table; it does not own a file directory (the working directory is bound at run time from sessions.set_project_root).

Methods

workspace.create

Create a new workspace. name and icon are persisted via a follow-up workspace.update because the underlying create path does not accept them.

Parameter	Type	Required	Description
`id`	string	yes	Workspace id (URL-safe slug)
`name`	string	yes	Human-readable display name
`description`	string	no	Free-text description
`icon`	string	no	Emoji or icon identifier

Response: { "ok": true, "workspace": { ...WorkspaceRecord... } }. The Panel's "New project" form uses this and then immediately calls channels.set_agent to bind the first channel.

workspace.list

List every workspace. Request: no params.

Response: { "workspaces": [ ...WorkspaceRecord... ] }.

workspace.get

Fetch a single workspace by id.

Parameter	Type	Required	Description
`id`	string	yes	Workspace id

Response: { "workspace": { ...WorkspaceRecord... } } or RESOURCE_NOT_FOUND: Workspace '<id>' not found.

workspace.update

Patch a workspace's metadata. Only the fields present in params are touched.

Parameter	Type	Required	Description
`id`	string	yes	Workspace id
`name`	string	no	New name
`description`	string	no	New description
`icon`	string	no	New icon

Response: { "ok": true, "workspace": { ...updated WorkspaceRecord... } } or RESOURCE_NOT_FOUND on a miss.

workspace.archive

Soft-delete a workspace (the row is removed; the underlying directory, if any, is not). The id remains reserved — recreate with a new row.

Parameter	Type	Required	Description
`id`	string	yes	Workspace id

Response: { "ok": true } on a successful archive; RESOURCE_NOT_FOUND: Workspace '<id>' not found on a miss.

Channel agent binding

These two methods live in the same module because they share the gateway::agent_binding seam with the agent_switch builtin tool — both surfaces get the same ghost-validation, no-op detection, and Bound / Unbound events.

channels.set_agent

Bind or unbind an agent to a channel. The two surfaces share the same handler.

Parameter	Type	Required	Description
`channel_id`	string	yes	Channel id
`agent_id`	string	no	Agent id; `null` / absent unbinds

Response (bind): { "ok", "previous_agent" | null, "no_op": false } on a fresh bind; { "ok", "previous_agent", "no_op": true } on a no-op rebind.

Response (unbind): { "ok", "previous_agent" | null }.

INVALID_PARAMS when the agent_id does not exist in the live AgentRegistry. A minimal server with agent_registry: None skips the validation (the prior lenient behaviour, kept only for minimal-server boot).

The same surface is reachable at the legacy workspace.set_agent path (no wire alias — both methods share the implementation). Prefer channels.set_agent for new code.

agents.bindings

Get every channel bound to each agent, sorted by channel id. Many-to-one aware: an agent bound to multiple channels appears once with all of them in the array.

Request: no params.

Response: { "bindings": { "agent-1": [ "discord", "telegram" ], … } }. The previous one-channel-per-agent map was lossy and was replaced when the new shape landed.

Methods that are not RPC

The following methods are described in earlier versions of this page but are not registered on the current aleph-server:

Method	Why it is not an RPC
`workspace.activate`	There is no "active workspace" concept at runtime — the agent loop reads the session's `project_root` (set via `sessions.set_project_root`) on every turn, so an "active" switch would be redundant.
`workspace.files`	Workspace storage is an `AgentEnvStore` row, not a directory listing. Use `fs.list_dir` (scoped to the project root) or the agent's own tool surface.
`workspace.delete`	The runtime exposes only `archive`; the row is reserved after archive.