@narumitw/pi-herdr 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,235 +3,233 @@ export const HERDR_AGENT_STATUSES = ["idle", "working", "blocked", "done", "unkn
3
3
  export type HerdrAgentStatus = (typeof HERDR_AGENT_STATUSES)[number];
4
4
 
5
5
  export interface HerdrPane {
6
- paneId: string;
7
- workspaceId: string;
8
- tabId: string;
9
- terminalId: string;
10
- focused: boolean;
11
- revision: number;
12
- agent?: string;
13
- agentName?: string;
14
- agentStatus: HerdrAgentStatus;
15
- displayAgent?: string;
16
- label?: string;
17
- stateLabels: Record<string, string>;
18
- terminalTitle?: string;
19
- title?: string;
6
+ paneId: string;
7
+ workspaceId: string;
8
+ tabId: string;
9
+ terminalId: string;
10
+ focused: boolean;
11
+ revision: number;
12
+ agent?: string;
13
+ agentName?: string;
14
+ agentStatus: HerdrAgentStatus;
15
+ displayAgent?: string;
16
+ label?: string;
17
+ stateLabels: Record<string, string>;
18
+ terminalTitle?: string;
19
+ title?: string;
20
20
  }
21
21
 
22
22
  export interface HerdrWorkspace {
23
- workspaceId: string;
24
- label?: string;
23
+ workspaceId: string;
24
+ label?: string;
25
25
  }
26
26
 
27
27
  export type HerdrPaneEvent =
28
- | { type: "created"; pane: HerdrPane }
29
- | { type: "closed" | "exited"; paneId: string; workspaceId: string }
30
- | {
31
- type: "moved";
32
- pane: HerdrPane;
33
- previousPaneId: string;
34
- previousWorkspaceId: string;
35
- }
36
- | {
37
- type: "agent_detected";
38
- paneId: string;
39
- workspaceId: string;
40
- agent?: string;
41
- finalStatus?: HerdrAgentStatus;
42
- released: boolean;
43
- }
44
- | {
45
- type: "agent_status_changed";
46
- paneId: string;
47
- workspaceId: string;
48
- agent?: string;
49
- agentStatus: HerdrAgentStatus;
50
- displayAgent?: string;
51
- stateLabels?: Record<string, string>;
52
- title?: string;
53
- };
28
+ | { type: "created"; pane: HerdrPane }
29
+ | { type: "closed" | "exited"; paneId: string; workspaceId: string }
30
+ | {
31
+ type: "moved";
32
+ pane: HerdrPane;
33
+ previousPaneId: string;
34
+ previousWorkspaceId: string;
35
+ }
36
+ | {
37
+ type: "agent_detected";
38
+ paneId: string;
39
+ workspaceId: string;
40
+ agent?: string;
41
+ finalStatus?: HerdrAgentStatus;
42
+ released: boolean;
43
+ }
44
+ | {
45
+ type: "agent_status_changed";
46
+ paneId: string;
47
+ workspaceId: string;
48
+ agent?: string;
49
+ agentStatus: HerdrAgentStatus;
50
+ displayAgent?: string;
51
+ stateLabels?: Record<string, string>;
52
+ title?: string;
53
+ };
54
54
 
55
55
  const HERDR_WIDGET_TOPOLOGY_SUBSCRIPTIONS = [
56
- { type: "pane.created" },
57
- { type: "pane.closed" },
58
- { type: "pane.moved" },
59
- { type: "pane.exited" },
60
- { type: "pane.agent_detected" },
56
+ { type: "pane.created" },
57
+ { type: "pane.closed" },
58
+ { type: "pane.moved" },
59
+ { type: "pane.exited" },
60
+ { type: "pane.agent_detected" },
61
61
  ] as const;
62
62
 
63
63
  export function herdrWidgetSubscriptions(panes: readonly HerdrPane[]) {
64
- return [
65
- ...HERDR_WIDGET_TOPOLOGY_SUBSCRIPTIONS.map((entry) => ({ ...entry })),
66
- ...panes
67
- .filter((pane) => pane.agent !== undefined)
68
- .map((pane) => ({ type: "pane.agent_status_changed", pane_id: pane.paneId })),
69
- ];
64
+ return [
65
+ ...HERDR_WIDGET_TOPOLOGY_SUBSCRIPTIONS.map((entry) => ({ ...entry })),
66
+ ...panes
67
+ .filter((pane) => pane.agent !== undefined)
68
+ .map((pane) => ({ type: "pane.agent_status_changed", pane_id: pane.paneId })),
69
+ ];
70
70
  }
71
71
 
72
72
  function isRecord(value: unknown): value is Record<string, unknown> {
73
- return typeof value === "object" && value !== null && !Array.isArray(value);
73
+ return typeof value === "object" && value !== null && !Array.isArray(value);
74
74
  }
75
75
 
76
76
  function requiredString(value: unknown): string | undefined {
77
- return typeof value === "string" && value.length > 0 ? value : undefined;
77
+ return typeof value === "string" && value.length > 0 ? value : undefined;
78
78
  }
79
79
 
80
80
  function optionalString(value: unknown): string | undefined {
81
- return typeof value === "string" ? value : undefined;
81
+ return typeof value === "string" ? value : undefined;
82
82
  }
83
83
 
84
84
  function agentStatus(value: unknown): HerdrAgentStatus | undefined {
85
- return typeof value === "string" && HERDR_AGENT_STATUSES.includes(value as HerdrAgentStatus)
86
- ? (value as HerdrAgentStatus)
87
- : undefined;
85
+ return typeof value === "string" && HERDR_AGENT_STATUSES.includes(value as HerdrAgentStatus)
86
+ ? (value as HerdrAgentStatus)
87
+ : undefined;
88
88
  }
89
89
 
90
90
  function stringRecord(value: unknown): Record<string, string> | undefined {
91
- if (!isRecord(value)) return undefined;
92
- const entries = Object.entries(value);
93
- if (!entries.every(([, entry]) => typeof entry === "string")) return undefined;
94
- return Object.fromEntries(entries) as Record<string, string>;
91
+ if (!isRecord(value)) return undefined;
92
+ const entries = Object.entries(value);
93
+ if (!entries.every(([, entry]) => typeof entry === "string")) return undefined;
94
+ return Object.fromEntries(entries) as Record<string, string>;
95
95
  }
96
96
 
97
97
  export function parseHerdrPane(value: unknown): HerdrPane | undefined {
98
- if (!isRecord(value)) return undefined;
99
- const paneId = requiredString(value.pane_id);
100
- const workspaceId = requiredString(value.workspace_id);
101
- const tabId = requiredString(value.tab_id);
102
- const terminalId = requiredString(value.terminal_id);
103
- const status = agentStatus(value.agent_status);
104
- const revision = value.revision;
105
- if (
106
- !paneId ||
107
- !workspaceId ||
108
- !tabId ||
109
- !terminalId ||
110
- !status ||
111
- typeof value.focused !== "boolean" ||
112
- typeof revision !== "number" ||
113
- !Number.isSafeInteger(revision) ||
114
- revision < 0
115
- ) {
116
- return undefined;
117
- }
118
- return {
119
- paneId,
120
- workspaceId,
121
- tabId,
122
- terminalId,
123
- focused: value.focused,
124
- revision,
125
- agent: optionalString(value.agent),
126
- agentName: optionalString(value.name),
127
- agentStatus: status,
128
- displayAgent: optionalString(value.display_agent),
129
- label: optionalString(value.label),
130
- stateLabels: stringRecord(value.state_labels) ?? {},
131
- terminalTitle:
132
- optionalString(value.terminal_title_stripped) ?? optionalString(value.terminal_title),
133
- title: optionalString(value.title),
134
- };
98
+ if (!isRecord(value)) return undefined;
99
+ const paneId = requiredString(value.pane_id);
100
+ const workspaceId = requiredString(value.workspace_id);
101
+ const tabId = requiredString(value.tab_id);
102
+ const terminalId = requiredString(value.terminal_id);
103
+ const status = agentStatus(value.agent_status);
104
+ const revision = value.revision;
105
+ if (
106
+ !paneId ||
107
+ !workspaceId ||
108
+ !tabId ||
109
+ !terminalId ||
110
+ !status ||
111
+ typeof value.focused !== "boolean" ||
112
+ typeof revision !== "number" ||
113
+ !Number.isSafeInteger(revision) ||
114
+ revision < 0
115
+ ) {
116
+ return undefined;
117
+ }
118
+ return {
119
+ paneId,
120
+ workspaceId,
121
+ tabId,
122
+ terminalId,
123
+ focused: value.focused,
124
+ revision,
125
+ agent: optionalString(value.agent),
126
+ agentName: optionalString(value.name),
127
+ agentStatus: status,
128
+ displayAgent: optionalString(value.display_agent),
129
+ label: optionalString(value.label),
130
+ stateLabels: stringRecord(value.state_labels) ?? {},
131
+ terminalTitle: optionalString(value.terminal_title_stripped) ?? optionalString(value.terminal_title),
132
+ title: optionalString(value.title),
133
+ };
135
134
  }
136
135
 
137
136
  export function parsePaneCurrentResult(value: unknown): HerdrPane {
138
- if (!isRecord(value) || value.type !== "pane_current") {
139
- throw new Error("Herdr returned an invalid current-pane response");
140
- }
141
- const pane = parseHerdrPane(value.pane);
142
- if (!pane) throw new Error("Herdr returned an invalid current pane");
143
- return pane;
137
+ if (!isRecord(value) || value.type !== "pane_current") {
138
+ throw new Error("Herdr returned an invalid current-pane response");
139
+ }
140
+ const pane = parseHerdrPane(value.pane);
141
+ if (!pane) throw new Error("Herdr returned an invalid current pane");
142
+ return pane;
144
143
  }
145
144
 
146
145
  export function parsePaneListResult(value: unknown): HerdrPane[] {
147
- if (!isRecord(value) || value.type !== "pane_list" || !Array.isArray(value.panes)) {
148
- throw new Error("Herdr returned an invalid pane-list response");
149
- }
150
- const panes = value.panes.map(parseHerdrPane);
151
- if (panes.some((pane) => pane === undefined)) {
152
- throw new Error("Herdr returned an invalid pane in the pane list");
153
- }
154
- return panes as HerdrPane[];
146
+ if (!isRecord(value) || value.type !== "pane_list" || !Array.isArray(value.panes)) {
147
+ throw new Error("Herdr returned an invalid pane-list response");
148
+ }
149
+ const panes = value.panes.map(parseHerdrPane);
150
+ if (panes.some((pane) => pane === undefined)) {
151
+ throw new Error("Herdr returned an invalid pane in the pane list");
152
+ }
153
+ return panes as HerdrPane[];
155
154
  }
156
155
 
157
156
  export function parseAgentListResult(value: unknown): HerdrPane[] {
158
- if (!isRecord(value) || value.type !== "agent_list" || !Array.isArray(value.agents)) {
159
- throw new Error("Herdr returned an invalid agent-list response");
160
- }
161
- return value.agents.flatMap((entry) => {
162
- const pane = parseHerdrPane(entry);
163
- return pane ? [pane] : [];
164
- });
157
+ if (!isRecord(value) || value.type !== "agent_list" || !Array.isArray(value.agents)) {
158
+ throw new Error("Herdr returned an invalid agent-list response");
159
+ }
160
+ return value.agents.flatMap((entry) => {
161
+ const pane = parseHerdrPane(entry);
162
+ return pane ? [pane] : [];
163
+ });
165
164
  }
166
165
 
167
166
  export function parseWorkspaceGetResult(value: unknown): HerdrWorkspace {
168
- if (!isRecord(value) || value.type !== "workspace_info" || !isRecord(value.workspace)) {
169
- throw new Error("Herdr returned an invalid workspace response");
170
- }
171
- const workspaceId = requiredString(value.workspace.workspace_id);
172
- if (!workspaceId) throw new Error("Herdr returned an invalid workspace identity");
173
- return { workspaceId, label: optionalString(value.workspace.label) };
167
+ if (!isRecord(value) || value.type !== "workspace_info" || !isRecord(value.workspace)) {
168
+ throw new Error("Herdr returned an invalid workspace response");
169
+ }
170
+ const workspaceId = requiredString(value.workspace.workspace_id);
171
+ if (!workspaceId) throw new Error("Herdr returned an invalid workspace identity");
172
+ return { workspaceId, label: optionalString(value.workspace.label) };
174
173
  }
175
174
 
176
175
  export function parseHerdrPaneEvent(value: unknown): HerdrPaneEvent | undefined {
177
- if (!isRecord(value) || typeof value.event !== "string" || !isRecord(value.data)) {
178
- return undefined;
179
- }
180
- const data = value.data;
181
-
182
- if (value.event === "pane.agent_status_changed") {
183
- const paneId = requiredString(data.pane_id);
184
- const workspaceId = requiredString(data.workspace_id);
185
- const status = agentStatus(data.agent_status);
186
- if (!paneId || !workspaceId || !status) return undefined;
187
- return {
188
- type: "agent_status_changed",
189
- paneId,
190
- workspaceId,
191
- agent: optionalString(data.agent),
192
- agentStatus: status,
193
- displayAgent: optionalString(data.display_agent),
194
- stateLabels: stringRecord(data.state_labels),
195
- title: optionalString(data.title),
196
- };
197
- }
198
-
199
- if (value.event === "pane_created") {
200
- const pane = parseHerdrPane(data.pane);
201
- return pane ? { type: "created", pane } : undefined;
202
- }
203
- if (value.event === "pane_closed" || value.event === "pane_exited") {
204
- const paneId = requiredString(data.pane_id);
205
- const workspaceId = requiredString(data.workspace_id);
206
- if (!paneId || !workspaceId) return undefined;
207
- return {
208
- type: value.event === "pane_closed" ? "closed" : "exited",
209
- paneId,
210
- workspaceId,
211
- };
212
- }
213
- if (value.event === "pane_moved") {
214
- const pane = parseHerdrPane(data.pane);
215
- const previousPaneId = requiredString(data.previous_pane_id);
216
- const previousWorkspaceId = requiredString(data.previous_workspace_id);
217
- if (!pane || !previousPaneId || !previousWorkspaceId) return undefined;
218
- return { type: "moved", pane, previousPaneId, previousWorkspaceId };
219
- }
220
- if (value.event === "pane_agent_detected") {
221
- const paneId = requiredString(data.pane_id);
222
- const workspaceId = requiredString(data.workspace_id);
223
- if (!paneId || !workspaceId || typeof data.released !== "boolean") return undefined;
224
- const finalStatus = data.final_status === null ? undefined : agentStatus(data.final_status);
225
- if (data.final_status !== undefined && data.final_status !== null && !finalStatus)
226
- return undefined;
227
- return {
228
- type: "agent_detected",
229
- paneId,
230
- workspaceId,
231
- agent: optionalString(data.agent),
232
- finalStatus,
233
- released: data.released,
234
- };
235
- }
236
- return undefined;
176
+ if (!isRecord(value) || typeof value.event !== "string" || !isRecord(value.data)) {
177
+ return undefined;
178
+ }
179
+ const data = value.data;
180
+
181
+ if (value.event === "pane.agent_status_changed") {
182
+ const paneId = requiredString(data.pane_id);
183
+ const workspaceId = requiredString(data.workspace_id);
184
+ const status = agentStatus(data.agent_status);
185
+ if (!paneId || !workspaceId || !status) return undefined;
186
+ return {
187
+ type: "agent_status_changed",
188
+ paneId,
189
+ workspaceId,
190
+ agent: optionalString(data.agent),
191
+ agentStatus: status,
192
+ displayAgent: optionalString(data.display_agent),
193
+ stateLabels: stringRecord(data.state_labels),
194
+ title: optionalString(data.title),
195
+ };
196
+ }
197
+
198
+ if (value.event === "pane_created") {
199
+ const pane = parseHerdrPane(data.pane);
200
+ return pane ? { type: "created", pane } : undefined;
201
+ }
202
+ if (value.event === "pane_closed" || value.event === "pane_exited") {
203
+ const paneId = requiredString(data.pane_id);
204
+ const workspaceId = requiredString(data.workspace_id);
205
+ if (!paneId || !workspaceId) return undefined;
206
+ return {
207
+ type: value.event === "pane_closed" ? "closed" : "exited",
208
+ paneId,
209
+ workspaceId,
210
+ };
211
+ }
212
+ if (value.event === "pane_moved") {
213
+ const pane = parseHerdrPane(data.pane);
214
+ const previousPaneId = requiredString(data.previous_pane_id);
215
+ const previousWorkspaceId = requiredString(data.previous_workspace_id);
216
+ if (!pane || !previousPaneId || !previousWorkspaceId) return undefined;
217
+ return { type: "moved", pane, previousPaneId, previousWorkspaceId };
218
+ }
219
+ if (value.event === "pane_agent_detected") {
220
+ const paneId = requiredString(data.pane_id);
221
+ const workspaceId = requiredString(data.workspace_id);
222
+ if (!paneId || !workspaceId || typeof data.released !== "boolean") return undefined;
223
+ const finalStatus = data.final_status === null ? undefined : agentStatus(data.final_status);
224
+ if (data.final_status !== undefined && data.final_status !== null && !finalStatus) return undefined;
225
+ return {
226
+ type: "agent_detected",
227
+ paneId,
228
+ workspaceId,
229
+ agent: optionalString(data.agent),
230
+ finalStatus,
231
+ released: data.released,
232
+ };
233
+ }
234
+ return undefined;
237
235
  }
@@ -0,0 +1,129 @@
1
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import type { HerdrWidgetObserver } from "./herdr-observer.js";
3
+ import { awaitHerdrSettingsWrites, herdrSettingsPath, readHerdrSettings, updateHerdrSettings } from "./settings.js";
4
+
5
+ export interface HerdrSettingsOptions {
6
+ settingsPath?: string;
7
+ }
8
+
9
+ export function createHerdrSettingsController(
10
+ pi: ExtensionAPI,
11
+ observer: HerdrWidgetObserver,
12
+ options: HerdrSettingsOptions = {},
13
+ ) {
14
+ const settingsPath = options.settingsPath ?? herdrSettingsPath();
15
+ let generation = 0;
16
+ let owner: ExtensionContext | undefined;
17
+ let controller = new AbortController();
18
+ let enabled = true;
19
+ let changes = Promise.resolve();
20
+ let menuOpen = false;
21
+ const current = (expected: number) => expected === generation && !controller.signal.aborted;
22
+
23
+ pi.registerCommand("herdr", {
24
+ description: "Configure the Herdr agent widget",
25
+ handler: async (args, ctx) => {
26
+ if (args.trim()) throw new Error("/herdr does not accept arguments.");
27
+ if (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc")) {
28
+ throw new Error("/herdr requires TUI or RPC mode.");
29
+ }
30
+ if (!owner || ctx.sessionManager !== owner.sessionManager || menuOpen) return;
31
+ const expected = generation;
32
+ const signal = controller.signal;
33
+ menuOpen = true;
34
+ try {
35
+ const [{ runMenu }, { createHerdrMenu }] = await Promise.all([
36
+ import("@narumitw/pi-tui-kit"),
37
+ import("./herdr-menu.js"),
38
+ ]);
39
+ if (!current(expected)) return;
40
+ await runMenu(
41
+ ctx,
42
+ createHerdrMenu({
43
+ settingsPath,
44
+ isEnabled: () => enabled,
45
+ toggle: (actionSignal) => {
46
+ const result = changes.then(async () => {
47
+ if (actionSignal.aborted || !current(expected) || !owner) return false;
48
+ // Once accepted, finish the explicit save even if the menu closes.
49
+ // Session replacement still prevents stale runtime publication.
50
+ const previous = enabled;
51
+ const actionOwner = owner;
52
+ try {
53
+ enabled = !previous;
54
+ if (enabled && actionOwner.mode === "tui") observer.start(actionOwner);
55
+ else await observer.shutdown(actionOwner);
56
+ if (!current(expected)) return false;
57
+ await updateHerdrSettings({ widget: enabled }, { settingsPath });
58
+ return current(expected);
59
+ } catch {
60
+ if (!current(expected)) return false;
61
+ enabled = previous;
62
+ try {
63
+ if (previous && actionOwner.mode === "tui") observer.start(actionOwner);
64
+ else await observer.shutdown(actionOwner);
65
+ } finally {
66
+ if (current(expected))
67
+ ctx.ui.notify(
68
+ "Herdr settings were not saved; the previous widget setting was restored. Check pi-herdr.json and its permissions.",
69
+ "warning",
70
+ );
71
+ }
72
+ return false;
73
+ }
74
+ });
75
+ changes = result.then(
76
+ () => undefined,
77
+ () => undefined,
78
+ );
79
+ return result;
80
+ },
81
+ }),
82
+ {
83
+ getState: () => undefined,
84
+ signal,
85
+ isCurrent: () => current(expected),
86
+ onError: () => {
87
+ if (current(expected)) ctx.ui.notify("The Herdr menu could not be displayed.", "error");
88
+ },
89
+ },
90
+ );
91
+ } finally {
92
+ if (expected === generation) menuOpen = false;
93
+ }
94
+ },
95
+ });
96
+
97
+ return {
98
+ async start(ctx: ExtensionContext) {
99
+ const expected = ++generation;
100
+ controller.abort();
101
+ controller = new AbortController();
102
+ menuOpen = false;
103
+ const previous = owner;
104
+ owner = ctx;
105
+ if (previous) await observer.shutdown(previous);
106
+ if (!current(expected)) return;
107
+ await changes;
108
+ if (!current(expected)) return;
109
+ const loaded = await readHerdrSettings(settingsPath);
110
+ if (!current(expected)) return;
111
+ enabled = loaded.settings.widget;
112
+ if (loaded.kind === "invalid" && ctx.hasUI)
113
+ ctx.ui.notify(
114
+ "Herdr ignored invalid pi-herdr.json settings and kept the widget enabled. Fix the file before saving.",
115
+ "warning",
116
+ );
117
+ if (enabled && ctx.mode === "tui") observer.start(ctx);
118
+ },
119
+ async shutdown(ctx: ExtensionContext) {
120
+ if (ctx.sessionManager !== owner?.sessionManager) return;
121
+ generation += 1;
122
+ controller.abort();
123
+ owner = undefined;
124
+ menuOpen = false;
125
+ await Promise.all([observer.shutdown(ctx), changes]);
126
+ await awaitHerdrSettingsWrites(settingsPath);
127
+ },
128
+ };
129
+ }