aboutsummaryrefslogtreecommitdiffstats
path: root/zellij-utils/src/plugin_api
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-12 18:44:24 +0200
committeruser <user@clank>2026-08-12 18:44:24 +0200
commit2c67579398835d51e625085ce3b22c22bc8f0cba (patch)
tree2b22d137d988f0bbf658ec4d37336f813933bfa1 /zellij-utils/src/plugin_api
parentsl0p: document workspace hints for consumers (diff)
downloadsl0ppij-2c67579398835d51e625085ce3b22c22bc8f0cba.tar.gz
sl0ppij-2c67579398835d51e625085ce3b22c22bc8f0cba.tar.xz
sl0ppij-2c67579398835d51e625085ce3b22c22bc8f0cba.zip
sl0p: --purpose flag and tab-level purpose
Completes the two pieces deferred from the first workspace-hints pass. `zellij run --purpose X` / `zellij action new-pane --purpose X` tag a pane at spawn time, which is what an agent wants for panes it creates itself; the OSC wrapper still works for programs that declare their own role. Not supported with --in-place, which replaces another pane rather than being a pane of its own: clap rejects the combination rather than accepting a flag that would do nothing. `tab name="work" purpose="agent-work"` gives a whole tab a role, reported by `list-tabs --json`. It rides the tab's ROOT layout node, reusing the pane field because a tab's root is the tab container and never itself a pane -- asserted by a test for the tightest case (a tab holding exactly one pane), since a leak there would silently mislabel a pane. The interesting part is why the flag first shipped broken. There are TWO protobuf boundaries -- the plugin API and the client->server IPC contract -- and a CLI flag must cross the second one. Defaulting the field in the conversion (what "no protoc" usually forces) compiles cleanly and then silently drops the value in transit, so --purpose parsed, printed a pane id, and did nothing. Fixed by adding the field to both contracts by hand, in the .proto AND the committed generated prost, kept in lockstep so a future regeneration reproduces it: protoc is only needed to regenerate, not to build. Both boundaries now have a round-trip test, and the IPC one was confirmed to fail when the wire read is removed. Sanitising moved to Grid::set_authoritative_purpose, the single choke point every out-of-band source passes through, after the CLI path was observed delivering `bad purpose; rm -rf /` intact into list-panes --json.
Diffstat (limited to 'zellij-utils/src/plugin_api')
-rw-r--r--zellij-utils/src/plugin_api/action.proto3
-rw-r--r--zellij-utils/src/plugin_api/action.rs15
-rw-r--r--zellij-utils/src/plugin_api/event.rs5
3 files changed, 23 insertions, 0 deletions
diff --git a/zellij-utils/src/plugin_api/action.proto b/zellij-utils/src/plugin_api/action.proto
index 1d896cef..4c6da631 100644
--- a/zellij-utils/src/plugin_api/action.proto
+++ b/zellij-utils/src/plugin_api/action.proto
@@ -328,6 +328,7 @@ message GoToTabNamePayload {
message NewFloatingPanePayload {
optional RunCommandAction command = 1;
bool near_current_pane = 2;
+ optional string purpose = 3;
}
message NewTiledPanePayload {
@@ -335,6 +336,7 @@ message NewTiledPanePayload {
optional resize.ResizeDirection direction = 2;
bool near_current_pane = 3;
optional bool borderless = 4;
+ optional string purpose = 5;
}
message MovePanePayload {
@@ -365,6 +367,7 @@ message NewBlockingPanePayload {
optional RunCommandAction command = 3;
optional UnblockCondition unblock_condition = 4;
bool near_current_pane = 5;
+ optional string purpose = 6;
}
message NewInPlacePanePayload {
diff --git a/zellij-utils/src/plugin_api/action.rs b/zellij-utils/src/plugin_api/action.rs
index e3cd29f8..c7bb144a 100644
--- a/zellij-utils/src/plugin_api/action.rs
+++ b/zellij-utils/src/plugin_api/action.rs
@@ -370,10 +370,12 @@ impl TryFrom<ProtobufAction> for Action {
Some(ProtobufActionName::NewFloatingPane) => match protobuf_action.optional_payload {
Some(OptionalPayload::NewFloatingPanePayload(payload)) => {
let near_current_pane = payload.near_current_pane;
+ let purpose = payload.purpose.clone();
if let Some(payload) = payload.command {
let pane_name = payload.pane_name.clone();
let run_command_action: RunCommandAction = payload.try_into()?;
Ok(Action::NewFloatingPane {
+ purpose: purpose.clone(),
command: Some(run_command_action),
pane_name,
coordinates: None,
@@ -383,6 +385,7 @@ impl TryFrom<ProtobufAction> for Action {
})
} else {
Ok(Action::NewFloatingPane {
+ purpose: purpose.clone(),
command: None,
pane_name: None,
coordinates: None,
@@ -401,11 +404,13 @@ impl TryFrom<ProtobufAction> for Action {
.and_then(|d| ProtobufResizeDirection::from_i32(d))
.and_then(|d| d.try_into().ok());
let near_current_pane = payload.near_current_pane;
+ let purpose = payload.purpose.clone();
let borderless = payload.borderless;
if let Some(payload) = payload.command {
let pane_name = payload.pane_name.clone();
let run_command_action: RunCommandAction = payload.try_into()?;
Ok(Action::NewTiledPane {
+ purpose: purpose.clone(),
direction,
command: Some(run_command_action),
pane_name,
@@ -416,6 +421,7 @@ impl TryFrom<ProtobufAction> for Action {
})
} else {
Ok(Action::NewTiledPane {
+ purpose: purpose.clone(),
direction,
command: None,
pane_name: None,
@@ -1036,6 +1042,7 @@ impl TryFrom<ProtobufAction> for Action {
Some(ProtobufActionName::NewStackedPane) => match protobuf_action.optional_payload {
Some(_) => Err("NewStackedPane should not have a payload"),
None => Ok(Action::NewStackedPane {
+ purpose: None,
command: None,
pane_name: None,
near_current_pane: false,
@@ -1056,7 +1063,9 @@ impl TryFrom<ProtobufAction> for Action {
.and_then(|uc| ProtobufUnblockCondition::from_i32(uc))
.and_then(|uc| uc.try_into().ok());
let near_current_pane = payload.near_current_pane;
+ let purpose = payload.purpose.clone();
Ok(Action::NewBlockingPane {
+ purpose: purpose.clone(),
placement,
pane_name,
command,
@@ -1418,6 +1427,7 @@ impl TryFrom<Action> for ProtobufAction {
pane_name,
coordinates: _coordinates,
near_current_pane,
+ purpose,
..
} => {
let command = run_command_action.and_then(|r| {
@@ -1430,6 +1440,7 @@ impl TryFrom<Action> for ProtobufAction {
name: ProtobufActionName::NewFloatingPane as i32,
optional_payload: Some(OptionalPayload::NewFloatingPanePayload(
NewFloatingPanePayload {
+ purpose: purpose.clone(),
command,
near_current_pane,
},
@@ -1441,6 +1452,7 @@ impl TryFrom<Action> for ProtobufAction {
command: run_command_action,
pane_name,
near_current_pane,
+ purpose,
borderless,
..
} => {
@@ -1459,6 +1471,7 @@ impl TryFrom<Action> for ProtobufAction {
name: ProtobufActionName::NewTiledPane as i32,
optional_payload: Some(OptionalPayload::NewTiledPanePayload(
NewTiledPanePayload {
+ purpose: purpose.clone(),
direction,
command,
near_current_pane,
@@ -1932,6 +1945,7 @@ impl TryFrom<Action> for ProtobufAction {
command,
unblock_condition,
near_current_pane,
+ purpose,
..
} => {
let placement: ProtobufNewPanePlacement = placement.try_into()?;
@@ -1949,6 +1963,7 @@ impl TryFrom<Action> for ProtobufAction {
name: ProtobufActionName::NewBlockingPane as i32,
optional_payload: Some(OptionalPayload::NewBlockingPanePayload(
NewBlockingPanePayload {
+ purpose: purpose.clone(),
placement: Some(placement),
pane_name,
command,
diff --git a/zellij-utils/src/plugin_api/event.rs b/zellij-utils/src/plugin_api/event.rs
index 2e905f22..6be6c6d0 100644
--- a/zellij-utils/src/plugin_api/event.rs
+++ b/zellij-utils/src/plugin_api/event.rs
@@ -1888,6 +1888,7 @@ impl TryFrom<ProtobufTabInfo> for TabInfo {
type Error = &'static str;
fn try_from(protobuf_tab_info: ProtobufTabInfo) -> Result<Self, &'static str> {
Ok(TabInfo {
+ purpose: None, // no protobuf field; plugins do not see tab purposes
position: protobuf_tab_info.position as usize,
name: protobuf_tab_info.name,
active: protobuf_tab_info.active,
@@ -2557,6 +2558,7 @@ fn serialize_tab_update_event_with_non_default_values() {
use prost::Message;
let tab_update_event = Event::TabUpdate(vec![
TabInfo {
+ purpose: None,
position: 0,
name: "First tab".to_owned(),
active: true,
@@ -2578,6 +2580,7 @@ fn serialize_tab_update_event_with_non_default_values() {
is_flashing_bell: false,
},
TabInfo {
+ purpose: None,
position: 1,
name: "Secondtab".to_owned(),
active: false,
@@ -2903,6 +2906,7 @@ fn serialize_session_update_event_with_non_default_values() {
use prost::Message;
let tab_infos = vec![
TabInfo {
+ purpose: None,
position: 0,
name: "First tab".to_owned(),
active: true,
@@ -2924,6 +2928,7 @@ fn serialize_session_update_event_with_non_default_values() {
is_flashing_bell: false,
},
TabInfo {
+ purpose: None,
position: 1,
name: "Secondtab".to_owned(),
active: false,