Resources

The Local API resource methods read and mutate the tree a session owns: the session, workspaces, sidebar groups, and tabs. Pane, agent, plugin, and server-control methods live on Panes and agents and Extensions and control.

Each entry lists params, the result discriminator, method-specific errors, and a runnable example. Result objects carry a type discriminator. For the error envelope see Error semantics; the generated requests, responses, and enums give the machine-generated shapes.

Identifiers and active-target defaults

Several resource methods accept optional selectors that pick a starting point when you omit an explicit id.

Public ids.

• workspace_id is a stable opaque string generated as w<micros_hex><counter_hex> (for example w1943cd2b11a1). The parsers also accept the legacy w_<n> and bare one-based integer forms. Results always use the generated w... form.
• group_id is a stable opaque string generated as g<micros_hex><counter_hex> for created groups. The first group is the built-in default and uses the fixed id default. The parsers also accept g_<n> and a bare one-based integer.
• tab_id is "<workspace_id>:t<encoded_number>" where the encoded number uses the 32-symbol alphabet 123456789ABCDEFGHJKMNPQRSTVWXYZ0 (one-based, bijective: tab 1 is 1, tab 10 is A). Closed tab numbers are not reused, so a tab_id remains a stable reference for the lifetime of the tab. Legacy t_<ws>_<tab> and "<workspace_id>:<n>" forms also parse.

Active-target defaults. Tab methods let the caller omit the target workspace. When both an explicit selector and an active fallback are missing, the method returns invalid_request.

• tab.create uses workspace_id when supplied, otherwise the active workspace. With no active workspace it returns workspace_not_found and the message no active workspace.
• workspace.create derives its location from the workspace creation source, workspace and group defaults, and the configured new-terminal cwd policy when neither cwd nor location is supplied. focus defaults to false, and is treated as true when no workspace is active.

Resource locations and placement

A ResourceLocation keeps the execution host and host-native path together:

{ "execution_host_id": "ssh:workbox:1", "path": "/srv/project" }

execution_host_id is local for the coordinator host or the id returned by connection.list for an SSH host. Paths are opaque to the coordinator for remote hosts. Gardn does not reinterpret a remote Unix path with local path rules.

Creation resolves placement from the first available source in this order:

1. Explicit location.
2. The pane or tab used as the split source.
3. The target workspace default, including its focused terminal location when available.
4. The target group default.
5. A local fallback.

Legacy cwd selects a local location. A request must not contain both cwd and location; that combination returns invalid_params.

The created resource and its initial pane report location in API responses. execution_host_id is also exposed as a convenience field on workspace, tab, and pane records.

Remote execution constraints

Remote execution requires a configured, reachable Unix SSH host. The coordinator runs the remote worker through system OpenSSH and uses the remote path without local canonicalization. Windows is not supported as a remote execution host.

If a connection is unavailable, creation fails instead of silently running the command locally. Existing local resources are not affected by a remote host failure.

Session

session.snapshot

Return a complete snapshot of the current session: every workspace, tab, pane, layout, and agent known to the server, plus the currently focused workspace, tab, and pane.

Params: none.

Result discriminator: session_snapshot. The snapshot field is a SessionSnapshot with version (product version), protocol (interactive client wire protocol), optional focused_workspace_id, focused_tab_id, and focused_pane_id, plus arrays of workspaces, tabs, panes, layouts, and agents. The focused ids are omitted (not null) when no workspace is active. Use this as the authoritative reconciliation point after reconnecting an event stream.

Errors: none method-specific. A snapshot of an empty session is valid and returns empty arrays.

Example:

{ "id": "snap:1", "method": "session.snapshot", "params": {} }

{
  "id": "snap:1",
  "result": {
    "type": "session_snapshot",
    "snapshot": {
      "version": "0.2.19",
      "protocol": 13,
      "focused_workspace_id": "w1943cd2b11a1",
      "focused_tab_id": "w1943cd2b11a1:t1",
      "focused_pane_id": "w1943cd2b11a1:p1",
      "workspaces": [
        {
          "workspace_id": "w1943cd2b11a1",
          "group_id": "default",
          "number": 1,
          "label": "gardn",
          "focused": true,
          "pane_count": 1,
          "tab_count": 1,
          "active_tab_id": "w1943cd2b11a1:t1",
          "agent_status": "idle"
        }
      ],
      "tabs": [
        {
          "tab_id": "w1943cd2b11a1:t1",
          "workspace_id": "w1943cd2b11a1",
          "number": 1,
          "label": "gardn",
          "focused": true,
          "pane_count": 1,
          "agent_status": "idle"
        }
      ],
      "panes": [],
      "layouts": [],
      "agents": []
    }
  }
}

Workspaces

A workspace is a terminal surface that owns tabs. Each workspace belongs to a group and carries a one-based number for display.

workspace.create

Create a new workspace with one initial tab and one root pane.

Params:

Result discriminator: workspace_created. Fields: workspace (WorkspaceInfo), tab (TabInfo), root_pane (PaneInfo). The server also emits workspace.created, tab.created, and pane.created events.

Errors:

Example:

{
  "id": "ws:create",
  "method": "workspace.create",
  "params": {
    "cwd": "/home/me/src/gardn",
    "label": "gardn-docs",
    "focus": true,
    "env": { "GARDN_TASK": "docs" }
  }
}

{
  "id": "ws:create",
  "result": {
    "type": "workspace_created",
    "workspace": {
      "workspace_id": "w1943cf02aa2",
      "group_id": "default",
      "number": 2,
      "label": "gardn-docs",
      "focused": true,
      "pane_count": 1,
      "tab_count": 1,
      "active_tab_id": "w1943cf02aa2:t1",
      "agent_status": "idle"
    },
    "tab": {
      "tab_id": "w1943cf02aa2:t1",
      "workspace_id": "w1943cf02aa2",
      "number": 1,
      "label": "gardn-docs",
      "focused": true,
      "pane_count": 1,
      "agent_status": "idle"
    },
    "root_pane": {}
  }
}

workspace.list

List every workspace in the session. The result mirrors what session.snapshot returns for the workspaces array.

Params: none.

Result discriminator: workspace_list. Fields: workspaces (WorkspaceInfo[]). Each entry includes workspace_id, group_id, one-based number, label, focused, pane_count, tab_count, active_tab_id, and agent_status.

Errors: none method-specific.

Example:

{ "id": "ws:list", "method": "workspace.list", "params": {} }

{
  "id": "ws:list",
  "result": {
    "type": "workspace_list",
    "workspaces": [
      {
        "workspace_id": "w1943cd2b11a1",
        "group_id": "default",
        "number": 1,
        "label": "gardn",
        "focused": true,
        "pane_count": 2,
        "tab_count": 1,
        "active_tab_id": "w1943cd2b11a1:t1",
        "agent_status": "working"
      }
    ]
  }
}

workspace.get

Return a single workspace by id.

Params:

Result discriminator: workspace_info. Fields: workspace (WorkspaceInfo).

Errors:

Example:

{ "id": "ws:get", "method": "workspace.get", "params": { "workspace_id": "w1943cd2b11a1" } }

{
  "id": "ws:get",
  "result": {
    "type": "workspace_info",
    "workspace": {
      "workspace_id": "w1943cd2b11a1",
      "group_id": "default",
      "number": 1,
      "label": "gardn",
      "focused": true,
      "pane_count": 2,
      "tab_count": 1,
      "active_tab_id": "w1943cd2b11a1:t1",
      "agent_status": "working"
    }
  }
}

workspace.focus

Move focus to a workspace. Switching workspace also switches the active group to the group that owns the workspace.

Params:

Result discriminator: workspace_info. Fields: workspace (WorkspaceInfo) with focused set to true. The server also emits a workspace.focused event.

Errors:

Example:

{ "id": "ws:focus", "method": "workspace.focus", "params": { "workspace_id": "w1943cd2b11a1" } }

{
  "id": "ws:focus",
  "result": {
    "type": "workspace_info",
    "workspace": {
      "workspace_id": "w1943cd2b11a1",
      "group_id": "default",
      "number": 1,
      "label": "gardn",
      "focused": true,
      "pane_count": 2,
      "tab_count": 1,
      "active_tab_id": "w1943cd2b11a1:t1",
      "agent_status": "working"
    }
  }
}

workspace.rename

Set or replace a workspace's custom label.

Params:

Result discriminator: workspace_info. Fields: workspace (WorkspaceInfo) reflecting the new label. The server persists the session and emits a workspace.renamed event.

Errors:

Example:

{
  "id": "ws:rename",
  "method": "workspace.rename",
  "params": { "workspace_id": "w1943cd2b11a1", "label": "docs-api" }
}

{
  "id": "ws:rename",
  "result": {
    "type": "workspace_info",
    "workspace": {
      "workspace_id": "w1943cd2b11a1",
      "group_id": "default",
      "number": 1,
      "label": "docs-api",
      "focused": true,
      "pane_count": 2,
      "tab_count": 1,
      "active_tab_id": "w1943cd2b11a1:t1",
      "agent_status": "working"
    }
  }
}

workspace.close

Close a workspace and every tab and pane it owns. The server releases the workspace's detached terminal runtimes.

Params:

Result discriminator: ok. The result object has no fields. The server emits a workspace.closed event whose payload includes a final WorkspaceInfo snapshot for the just-closed workspace.

Errors:

Example:

{ "id": "ws:close", "method": "workspace.close", "params": { "workspace_id": "w1943cf02aa2" } }

{ "id": "ws:close", "result": { "type": "ok" } }

workspace.move_to_group

Move a workspace into a different sidebar group.

Params:

Result: the method is declared in the schema and parsed by the server. The current dispatch table has no handler for it, so the request passes validation and then returns not_implemented with the message method not implemented yet. Do not rely on it to move workspaces programmatically. In the running app, group moves are performed by sidebar drag handling, not by this Local API method.

Errors:

Example:

{
  "id": "ws:move",
  "method": "workspace.move_to_group",
  "params": { "workspace_id": "w1943cd2b11a1", "group_id": "g1943cf10c3" }
}

{ "id": "ws:move", "error": { "code": "not_implemented", "message": "method not implemented yet" } }

Groups

Groups are sidebar containers for workspaces. The session starts with one built-in default group whose group_id is default. Created groups receive generated ids. The server does not emit events for group mutations; callers that need to track group changes must poll group.list.

group.list

List every group in the session.

Params: none.

Result discriminator: group_list. Fields: groups (GroupInfo[]) where each entry has group_id, one-based number, name, icon, focused, workspace_count, and optional default_location ({ execution_host_id, path }). Exactly one group has focused: true.

Errors: none method-specific.

Example:

{ "id": "grp:list", "method": "group.list", "params": {} }

{
  "id": "grp:list",
  "result": {
    "type": "group_list",
    "groups": [
      {
        "group_id": "default",
        "number": 1,
        "name": "group 1",
        "icon": "☀",
        "focused": true,
        "workspace_count": 1
      },
      {
        "group_id": "g1943cf10c3",
        "number": 2,
        "name": "side",
        "icon": "☁",
        "focused": false,
        "workspace_count": 0
      }
    ]
  }
}

group.focus

Make a group the active sidebar group. Focusing a group updates the group filter and returns the focused group's current resource summary.

Params:

Result discriminator: group_info. The returned group has focused: true. The session is persisted.

Errors:

{ "id": "grp:focus", "method": "group.focus", "params": { "group_id": "g1943cf10c3" } }

group.create

Create a new group. The new group receives a generated group_id, the supplied name, the default group icon, and optional default_location. It does not become the active group. Invalid placement fails without creating the group.

Params:

Result discriminator: group_info. Fields: group (GroupInfo) for the new group, with focused: false, workspace_count: 0, and default_location when supplied. The session is persisted.

Errors:

Example:

{
  "id": "grp:create",
  "method": "group.create",
  "params": {
    "name": "side",
    "default_location": {
      "execution_host_id": "ssh:workbox:1",
      "path": "/srv/work"
    }
  }
}

{
  "id": "grp:create",
  "result": {
    "type": "group_info",
    "group": {
      "group_id": "g1943cf10c3",
      "number": 2,
      "name": "side",
      "icon": "☀",
      "focused": false,
      "workspace_count": 0,
      "default_location": {
        "execution_host_id": "ssh:workbox:1",
        "path": "/srv/work"
      }
    }
  }
}

group.rename

Rename a group.

Params:

Result discriminator: group_info. Fields: group (GroupInfo) with the updated name. The session is persisted.

Errors:

Example:

{
  "id": "grp:rename",
  "method": "group.rename",
  "params": { "group_id": "g1943cf10c3", "name": "experiments" }
}

{
  "id": "grp:rename",
  "result": {
    "type": "group_info",
    "group": {
      "group_id": "g1943cf10c3",
      "number": 2,
      "name": "experiments",
      "icon": "☀",
      "focused": false,
      "workspace_count": 0
    }
  }
}

group.delete

Delete a group. Deleting a group closes every workspace that belongs to it and releases those workspaces' terminal runtimes. The last remaining group cannot be deleted.

Params:

Result discriminator: ok. The result object has no fields. If the deleted group was active, focus moves to the first remaining group. The session is persisted.

Errors:

Example:

{ "id": "grp:delete", "method": "group.delete", "params": { "group_id": "g1943cf10c3" } }

{ "id": "grp:delete", "result": { "type": "ok" } }

Tabs

A tab belongs to exactly one workspace and owns a pane layout. The tab_id encodes both the workspace and the tab's stable one-based number.

tab.list

List tabs. With no workspace_id, every tab in every workspace is returned.

Params:

Result discriminator: tab_list. Fields: tabs (TabInfo[]) where each entry has tab_id, workspace_id, one-based number, label, focused, pane_count, and agent_status.

Errors:

Example:

{ "id": "tab:list", "method": "tab.list", "params": { "workspace_id": "w1943cd2b11a1" } }

{
  "id": "tab:list",
  "result": {
    "type": "tab_list",
    "tabs": [
      {
        "tab_id": "w1943cd2b11a1:t1",
        "workspace_id": "w1943cd2b11a1",
        "number": 1,
        "label": "gardn",
        "focused": true,
        "pane_count": 2,
        "agent_status": "working"
      }
    ]
  }
}

tab.get

Return a single tab by id.

Params:

Result discriminator: tab_info. Fields: tab (TabInfo).

Errors:

Example:

{ "id": "tab:get", "method": "tab.get", "params": { "tab_id": "w1943cd2b11a1:t1" } }

{
  "id": "tab:get",
  "result": {
    "type": "tab_info",
    "tab": {
      "tab_id": "w1943cd2b11a1:t1",
      "workspace_id": "w1943cd2b11a1",
      "number": 1,
      "label": "gardn",
      "focused": true,
      "pane_count": 2,
      "agent_status": "working"
    }
  }
}

tab.create

Create a new tab in a workspace. The tab is created with one root pane. When workspace_id is omitted, the active workspace is used; with no active workspace the request fails.

Params:

Result discriminator: tab_created. Fields: tab (TabInfo), root_pane (PaneInfo). The server persists the session and emits tab.created and pane.created events.

Errors:

Example:

{
  "id": "tab:create",
  "method": "tab.create",
  "params": {
    "workspace_id": "w1943cd2b11a1",
    "label": "logs",
    "focus": true,
    "env": { "RUST_LOG": "debug" }
  }
}

{
  "id": "tab:create",
  "result": {
    "type": "tab_created",
    "tab": {
      "tab_id": "w1943cd2b11a1:t2",
      "workspace_id": "w1943cd2b11a1",
      "number": 2,
      "label": "logs",
      "focused": true,
      "pane_count": 1,
      "agent_status": "idle"
    },
    "root_pane": {}
  }
}

tab.focus

Move focus to a tab. Focusing a tab also switches the owning workspace to active.

Params:

Result discriminator: tab_info. Fields: tab (TabInfo) with focused: true. The server emits a tab.focused event.

Errors:

Example:

{ "id": "tab:focus", "method": "tab.focus", "params": { "tab_id": "w1943cd2b11a1:t2" } }

{
  "id": "tab:focus",
  "result": {
    "type": "tab_info",
    "tab": {
      "tab_id": "w1943cd2b11a1:t2",
      "workspace_id": "w1943cd2b11a1",
      "number": 2,
      "label": "logs",
      "focused": true,
      "pane_count": 1,
      "agent_status": "idle"
    }
  }
}

tab.rename

Set or replace a tab's custom label.

Params:

Result discriminator: tab_info. Fields: tab (TabInfo) reflecting the new label. The server persists the session and emits a tab.renamed event.

Errors:

Example:

{
  "id": "tab:rename",
  "method": "tab.rename",
  "params": { "tab_id": "w1943cd2b11a1:t2", "label": "build" }
}

{
  "id": "tab:rename",
  "result": {
    "type": "tab_info",
    "tab": {
      "tab_id": "w1943cd2b11a1:t2",
      "workspace_id": "w1943cd2b11a1",
      "number": 2,
      "label": "build",
      "focused": true,
      "pane_count": 1,
      "agent_status": "idle"
    }
  }
}

tab.close

Close a tab and release the terminals it owned. The owning workspace persists even if the closed tab was its last; the workspace then has zero tabs until a new one is created.

Params:

Result discriminator: ok. The result object has no fields. The server persists the session and emits a tab.closed event whose payload carries the closed tab_id and its workspace_id.

Errors:

Example:

{ "id": "tab:close", "method": "tab.close", "params": { "tab_id": "w1943cd2b11a1:t2" } }

{ "id": "tab:close", "result": { "type": "ok" } }