@howaboua/pi-shepherdr 0.1.2 → 0.1.4

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.
@@ -0,0 +1,291 @@
1
+ import {
2
+ cp,
3
+ mkdir,
4
+ mkdtemp,
5
+ readdir,
6
+ readFile,
7
+ rename,
8
+ rm,
9
+ stat,
10
+ writeFile,
11
+ } from "node:fs/promises";
12
+ import { homedir } from "node:os";
13
+ import { join, resolve } from "node:path";
14
+ import { fileURLToPath, pathToFileURL } from "node:url";
15
+
16
+ const PROFILE_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
17
+ const AGENT_DIRECTORY =
18
+ process.env["PI_CODING_AGENT_DIR"] ?? join(homedir(), ".pi", "agent");
19
+ const PROFILES_ROOT = join(AGENT_DIRECTORY, "shepherdr");
20
+ const PROFILES_DIRECTORY = join(PROFILES_ROOT, "profiles");
21
+ const PROFILE_INSTALL_MARKER = join(PROFILES_ROOT, ".profiles-initialized");
22
+ const BUNDLED_PROFILES_DIRECTORY = fileURLToPath(
23
+ new URL("../profiles", import.meta.url),
24
+ );
25
+
26
+ export interface AgentProfile {
27
+ accepts: string[];
28
+ description: string;
29
+ model: string;
30
+ name: string;
31
+ piArgs: string[];
32
+ prepare?: string;
33
+ prompt?: string;
34
+ promptPath?: string;
35
+ thinking: string;
36
+ }
37
+
38
+ interface ProfilePreparationInput {
39
+ base?: string;
40
+ cwd: string;
41
+ message: string;
42
+ }
43
+
44
+ type ProfilePreparationContext = ProfilePreparationInput & { local: boolean };
45
+
46
+ interface ProfileFile {
47
+ accepts?: unknown;
48
+ description?: unknown;
49
+ model?: unknown;
50
+ pi_args?: unknown;
51
+ prepare?: unknown;
52
+ prompt?: unknown;
53
+ thinking?: unknown;
54
+ }
55
+
56
+ function stringArray(value: unknown, field: string): string[] {
57
+ if (
58
+ !Array.isArray(value) ||
59
+ value.some((item) => typeof item !== "string" || item.length === 0)
60
+ ) {
61
+ throw new Error(`${field} must be an array of non-empty strings`);
62
+ }
63
+ return value;
64
+ }
65
+
66
+ function optionalString(value: unknown, field: string): string | undefined {
67
+ if (value === undefined) return undefined;
68
+ if (typeof value !== "string" || value.trim().length === 0) {
69
+ throw new Error(`${field} must be a non-empty string`);
70
+ }
71
+ return value.trim();
72
+ }
73
+
74
+ async function readProfile(
75
+ name: string,
76
+ directory: string,
77
+ ): Promise<AgentProfile> {
78
+ const path = join(directory, "profile.json");
79
+ let parsed: ProfileFile;
80
+ try {
81
+ parsed = JSON.parse(await readFile(path, "utf8")) as ProfileFile;
82
+ } catch (error) {
83
+ throw new Error(
84
+ `invalid ${name} profile: ${error instanceof Error ? error.message : String(error)}`,
85
+ );
86
+ }
87
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
88
+ throw new Error(`${name} profile must be an object`);
89
+ }
90
+ const allowed = new Set([
91
+ "accepts",
92
+ "description",
93
+ "model",
94
+ "pi_args",
95
+ "prepare",
96
+ "prompt",
97
+ "thinking",
98
+ ]);
99
+ const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
100
+ if (unknown.length > 0) {
101
+ throw new Error(`unknown ${name} profile field(s): ${unknown.join(", ")}`);
102
+ }
103
+ const description = optionalString(parsed.description, `${name}.description`);
104
+ if (!description) throw new Error(`${name}.description is required`);
105
+ const model = optionalString(parsed.model, `${name}.model`);
106
+ if (!model) throw new Error(`${name}.model is required`);
107
+ const thinking = optionalString(parsed.thinking, `${name}.thinking`);
108
+ if (!thinking) throw new Error(`${name}.thinking is required`);
109
+ const promptPath = optionalString(parsed.prompt, `${name}.prompt`);
110
+ const preparePath = optionalString(parsed.prepare, `${name}.prepare`);
111
+ const resolvedPromptPath = promptPath
112
+ ? resolve(directory, promptPath)
113
+ : undefined;
114
+ const prepare = preparePath ? resolve(directory, preparePath) : undefined;
115
+ if (resolvedPromptPath && !(await stat(resolvedPromptPath)).isFile()) {
116
+ throw new Error(`${name}.prompt is not a file`);
117
+ }
118
+ if (prepare && !(await stat(prepare)).isFile()) {
119
+ throw new Error(`${name}.prepare is not a file`);
120
+ }
121
+ return {
122
+ name,
123
+ description,
124
+ model,
125
+ thinking,
126
+ accepts: parsed.accepts
127
+ ? stringArray(parsed.accepts, `${name}.accepts`)
128
+ : [],
129
+ piArgs: parsed.pi_args
130
+ ? stringArray(parsed.pi_args, `${name}.pi_args`)
131
+ : [],
132
+ ...(resolvedPromptPath
133
+ ? {
134
+ prompt: await readFile(resolvedPromptPath, "utf8"),
135
+ promptPath: resolvedPromptPath,
136
+ }
137
+ : {}),
138
+ ...(prepare ? { prepare } : {}),
139
+ };
140
+ }
141
+
142
+ function hasCode(error: unknown, ...codes: string[]): boolean {
143
+ return (
144
+ error instanceof Error &&
145
+ "code" in error &&
146
+ typeof error.code === "string" &&
147
+ codes.includes(error.code)
148
+ );
149
+ }
150
+
151
+ async function exists(path: string): Promise<boolean> {
152
+ try {
153
+ await stat(path);
154
+ return true;
155
+ } catch (error) {
156
+ if (hasCode(error, "ENOENT")) return false;
157
+ throw error;
158
+ }
159
+ }
160
+
161
+ async function installProfile(name: string): Promise<void> {
162
+ const target = join(PROFILES_DIRECTORY, name);
163
+ if (await exists(target)) return;
164
+ const stagingRoot = await mkdtemp(join(PROFILES_ROOT, `.${name}-`));
165
+ const staging = join(stagingRoot, name);
166
+ try {
167
+ await cp(join(BUNDLED_PROFILES_DIRECTORY, name), staging, {
168
+ errorOnExist: true,
169
+ force: false,
170
+ recursive: true,
171
+ });
172
+ try {
173
+ await rename(staging, target);
174
+ } catch (error) {
175
+ if (!hasCode(error, "EEXIST", "ENOTEMPTY")) throw error;
176
+ }
177
+ } finally {
178
+ await rm(stagingRoot, { force: true, recursive: true });
179
+ }
180
+ }
181
+
182
+ export async function installAgentProfiles(): Promise<void> {
183
+ if (await exists(PROFILE_INSTALL_MARKER)) return;
184
+ await mkdir(PROFILES_DIRECTORY, { mode: 0o700, recursive: true });
185
+ const entries = await readdir(BUNDLED_PROFILES_DIRECTORY, {
186
+ withFileTypes: true,
187
+ });
188
+ for (const entry of entries.sort((left, right) =>
189
+ left.name.localeCompare(right.name),
190
+ )) {
191
+ if (!entry.isDirectory()) continue;
192
+ if (!PROFILE_NAME.test(entry.name)) {
193
+ throw new Error(`invalid bundled agent profile: ${entry.name}`);
194
+ }
195
+ await installProfile(entry.name);
196
+ }
197
+ try {
198
+ await writeFile(PROFILE_INSTALL_MARKER, "1\n", {
199
+ flag: "wx",
200
+ mode: 0o600,
201
+ });
202
+ } catch (error) {
203
+ if (!hasCode(error, "EEXIST")) throw error;
204
+ }
205
+ }
206
+
207
+ export async function loadAgentProfiles(): Promise<Map<string, AgentProfile>> {
208
+ const profiles = new Map<string, AgentProfile>();
209
+ let entries;
210
+ try {
211
+ entries = await readdir(PROFILES_DIRECTORY, { withFileTypes: true });
212
+ } catch (error) {
213
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return profiles;
214
+ throw error;
215
+ }
216
+ for (const entry of entries.sort((left, right) =>
217
+ left.name.localeCompare(right.name),
218
+ )) {
219
+ if (!entry.isDirectory()) continue;
220
+ if (!PROFILE_NAME.test(entry.name)) {
221
+ throw new Error(`invalid agent profile directory: ${entry.name}`);
222
+ }
223
+ profiles.set(
224
+ entry.name,
225
+ await readProfile(entry.name, join(PROFILES_DIRECTORY, entry.name)),
226
+ );
227
+ }
228
+ return profiles;
229
+ }
230
+
231
+ function promptArgument(
232
+ profile: AgentProfile,
233
+ targetLocal: boolean,
234
+ ): string | undefined {
235
+ if (
236
+ targetLocal &&
237
+ profile.promptPath &&
238
+ ![...profile.promptPath].some((character) => /\p{Cc}/u.test(character))
239
+ ) {
240
+ return profile.promptPath;
241
+ }
242
+ return profile.prompt
243
+ ?.replace(/\p{Cc}+/gu, " ")
244
+ .replace(/\s+/gu, " ")
245
+ .trim();
246
+ }
247
+
248
+ export function profileAgentArgs(
249
+ profile: AgentProfile,
250
+ options: { targetLocal?: boolean } = {},
251
+ ): string[] {
252
+ const prompt = promptArgument(profile, options.targetLocal !== false);
253
+ return [
254
+ "--model",
255
+ profile.model,
256
+ "--thinking",
257
+ profile.thinking,
258
+ ...(prompt ? ["--append-system-prompt", prompt] : []),
259
+ ...profile.piArgs,
260
+ ];
261
+ }
262
+
263
+ export async function prepareProfileMessage(
264
+ profile: AgentProfile,
265
+ input: ProfilePreparationInput,
266
+ options: { targetLocal?: boolean } = {},
267
+ ): Promise<string> {
268
+ if (input.base && !profile.accepts.includes("base")) {
269
+ throw new Error(`base is not supported by ${profile.name}`);
270
+ }
271
+ if (profile.prepare) {
272
+ const metadata = await stat(profile.prepare);
273
+ const module = (await import(
274
+ `${pathToFileURL(profile.prepare).href}?mtime=${metadata.mtimeMs}`
275
+ )) as { prepare?: (value: ProfilePreparationContext) => unknown };
276
+ if (typeof module.prepare !== "function") {
277
+ throw new Error(`${profile.name}.prepare must export prepare()`);
278
+ }
279
+ const prepared = await module.prepare({
280
+ ...input,
281
+ local: options.targetLocal !== false,
282
+ });
283
+ if (typeof prepared !== "string" || prepared.trim().length === 0) {
284
+ throw new Error(`${profile.name}.prepare must return a non-empty string`);
285
+ }
286
+ return prepared;
287
+ }
288
+ return input.base
289
+ ? `Review base: ${input.base}\n\n${input.message}`
290
+ : input.message;
291
+ }
@@ -1,14 +1,14 @@
1
1
  // @howaboua/pi-shepherdr managed bridge
2
- import { open, stat } from "node:fs/promises";
2
+ import { open, readFile, stat } from "node:fs/promises";
3
3
  import { createConnection } from "node:net";
4
4
  import { homedir } from "node:os";
5
5
  import { dirname, join, resolve } from "node:path";
6
6
 
7
- const BRIDGE_VERSION = 1;
7
+ const BRIDGE_VERSION = 3;
8
8
  const MAX_FRAME_BYTES = 8 * 1024 * 1024;
9
9
  const READ_CHUNK_BYTES = 64 * 1024;
10
10
  const subscriptions = new Map();
11
- const assistantCache = new Map();
11
+ const sessionCache = new Map();
12
12
 
13
13
  function argument(name) {
14
14
  const index = process.argv.indexOf(`--${name}`);
@@ -212,10 +212,8 @@ function subscribe(id, requested) {
212
212
  });
213
213
  }
214
214
 
215
- function assistantFromEntry(entry) {
216
- const message = entry.message;
217
- if (!message || typeof message !== "object" || message.role !== "assistant")
218
- return undefined;
215
+ function assistantFromMessage(id, message) {
216
+ if (message.role !== "assistant") return undefined;
219
217
  const text = [];
220
218
  if (typeof message.content === "string") text.push(message.content);
221
219
  else if (Array.isArray(message.content)) {
@@ -234,31 +232,140 @@ function assistantFromEntry(entry) {
234
232
  typeof message.stopReason === "string" ? message.stopReason : undefined;
235
233
  if (!joined && stopReason !== "error") return undefined;
236
234
  return {
237
- id: entry.id,
235
+ id,
238
236
  text: joined,
239
237
  ...(stopReason ? { stopReason } : {}),
240
238
  };
241
239
  }
242
240
 
243
- async function latestAssistant(path, size) {
241
+ function userFromMessage(id, message) {
242
+ if (message.role !== "user") return undefined;
243
+ const text = [];
244
+ if (typeof message.content === "string") text.push(message.content);
245
+ else if (Array.isArray(message.content)) {
246
+ for (const part of message.content) {
247
+ if (
248
+ part &&
249
+ typeof part === "object" &&
250
+ part.type === "text" &&
251
+ typeof part.text === "string"
252
+ )
253
+ text.push(part.text);
254
+ }
255
+ }
256
+ const joined = text.join("");
257
+ return joined ? { id, text: joined } : undefined;
258
+ }
259
+
260
+ function askChoice(value) {
261
+ if (!value || typeof value !== "object" || typeof value.label !== "string")
262
+ return undefined;
263
+ return {
264
+ label: value.label,
265
+ ...(typeof value.description === "string"
266
+ ? { description: value.description }
267
+ : {}),
268
+ };
269
+ }
270
+
271
+ function askPrompt(value) {
272
+ if (!value || typeof value !== "object" || typeof value.title !== "string")
273
+ return undefined;
274
+ return {
275
+ title: value.title,
276
+ multiple: value.multiple === true,
277
+ choices: (Array.isArray(value.choices) ? value.choices : [])
278
+ .map(askChoice)
279
+ .filter(Boolean),
280
+ ...(typeof value.body === "string" ? { body: value.body } : {}),
281
+ };
282
+ }
283
+
284
+ function askCall(value) {
285
+ if (
286
+ !value ||
287
+ typeof value !== "object" ||
288
+ value.type !== "toolCall" ||
289
+ value.name !== "ask" ||
290
+ typeof value.id !== "string" ||
291
+ !value.arguments ||
292
+ typeof value.arguments !== "object"
293
+ )
294
+ return undefined;
295
+ const prompts = (
296
+ Array.isArray(value.arguments.prompts) ? value.arguments.prompts : []
297
+ )
298
+ .map(askPrompt)
299
+ .filter(Boolean);
300
+ if (prompts.length === 0) return undefined;
301
+ return {
302
+ toolCallId: value.id,
303
+ handoff: value.arguments.handoff === true,
304
+ prompts,
305
+ };
306
+ }
307
+
308
+ async function sessionView(path, size) {
244
309
  const file = await open(path, "r");
245
310
  let targetId;
311
+ let assistant;
312
+ let assistantDepth;
313
+ let ask;
314
+ let depth = 0;
315
+ let user;
316
+ let userDepth;
317
+ const resolved = new Set();
318
+ const result = () => ({
319
+ ...(assistant ? { assistant } : {}),
320
+ ...(ask ? { ask } : {}),
321
+ ...(user ? { user } : {}),
322
+ ...(assistantDepth !== undefined && userDepth !== undefined
323
+ ? { assistantAfterUser: assistantDepth < userDepth }
324
+ : {}),
325
+ });
246
326
  const inspect = (line) => {
247
- if (line.length === 0) return undefined;
327
+ if (line.length === 0) return false;
248
328
  let entry;
249
329
  try {
250
330
  entry = JSON.parse(line.toString("utf8"));
251
331
  } catch {
252
- return undefined;
332
+ return false;
253
333
  }
254
- if (typeof entry.id !== "string") return undefined;
334
+ if (typeof entry.id !== "string") return false;
255
335
  targetId ??= entry.id;
256
- if (entry.id !== targetId) return undefined;
257
- const assistant = assistantFromEntry(entry);
258
- if (assistant) return assistant;
259
- if (typeof entry.parentId !== "string") return null;
336
+ if (entry.id !== targetId) return false;
337
+ const currentDepth = depth;
338
+ depth += 1;
339
+ const message = entry.message;
340
+ if (message && typeof message === "object") {
341
+ if (
342
+ (message.role === "toolResult" || message.role === "tool") &&
343
+ typeof (message.toolCallId ?? message.tool_call_id) === "string"
344
+ )
345
+ resolved.add(message.toolCallId ?? message.tool_call_id);
346
+ if (!assistant) {
347
+ assistant = assistantFromMessage(entry.id, message);
348
+ if (assistant) assistantDepth = currentDepth;
349
+ }
350
+ if (!user) {
351
+ user = userFromMessage(entry.id, message);
352
+ if (user) userDepth = currentDepth;
353
+ }
354
+ if (
355
+ !ask &&
356
+ message.role === "assistant" &&
357
+ Array.isArray(message.content)
358
+ )
359
+ ask = [...message.content]
360
+ .reverse()
361
+ .map(askCall)
362
+ .find(
363
+ (candidate) => candidate && !resolved.has(candidate.toolCallId),
364
+ );
365
+ }
366
+ if (typeof entry.parentId !== "string") return true;
260
367
  targetId = entry.parentId;
261
- return undefined;
368
+ return false;
262
369
  };
263
370
 
264
371
  try {
@@ -273,34 +380,33 @@ async function latestAssistant(path, size) {
273
380
  let lineEnd = data.length;
274
381
  for (let index = data.length - 1; index >= 0; index -= 1) {
275
382
  if (data[index] !== 0x0a) continue;
276
- const result = inspect(data.subarray(index + 1, lineEnd));
277
- if (result !== undefined) return result ?? undefined;
383
+ if (inspect(data.subarray(index + 1, lineEnd))) return result();
278
384
  lineEnd = index;
279
385
  }
280
386
  partial = data.subarray(0, lineEnd);
281
387
  }
282
- const result = inspect(partial);
283
- return result ?? undefined;
388
+ inspect(partial);
389
+ return result();
284
390
  } finally {
285
391
  await file.close();
286
392
  }
287
393
  }
288
394
 
289
- async function latest(path) {
290
- if (!path) return undefined;
395
+ async function view(path) {
396
+ if (!path) return {};
291
397
  const expanded = expandHome(path);
292
398
  let metadata;
293
399
  try {
294
400
  metadata = await stat(expanded);
295
401
  } catch (error) {
296
- if (error.code === "ENOENT") return undefined;
402
+ if (error.code === "ENOENT") return {};
297
403
  throw error;
298
404
  }
299
- const cached = assistantCache.get(expanded);
405
+ const cached = sessionCache.get(expanded);
300
406
  if (cached?.size === metadata.size && cached.mtimeMs === metadata.mtimeMs)
301
407
  return cached.result;
302
- const result = await latestAssistant(expanded, metadata.size);
303
- assistantCache.set(expanded, {
408
+ const result = await sessionView(expanded, metadata.size);
409
+ sessionCache.set(expanded, {
304
410
  size: metadata.size,
305
411
  mtimeMs: metadata.mtimeMs,
306
412
  result,
@@ -321,6 +427,19 @@ async function directory(value, fallback) {
321
427
  return path;
322
428
  }
323
429
 
430
+ async function keybindings() {
431
+ const directory =
432
+ process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
433
+ try {
434
+ const value = JSON.parse(
435
+ await readFile(join(directory, "keybindings.json"), "utf8"),
436
+ );
437
+ return value && typeof value === "object" ? value : {};
438
+ } catch {
439
+ return {};
440
+ }
441
+ }
442
+
324
443
  function serializableError(error) {
325
444
  return {
326
445
  message: error instanceof Error ? error.message : String(error),
@@ -350,7 +469,8 @@ async function handle(message) {
350
469
  subscriptions.delete(message.subscription);
351
470
  return { unsubscribed: true };
352
471
  }
353
- if (message.op === "latest") return latest(message.path);
472
+ if (message.op === "view") return view(message.path);
473
+ if (message.op === "keybindings") return keybindings();
354
474
  if (message.op === "directory")
355
475
  return directory(message.value, message.fallback);
356
476
  throw new Error(`unsupported Shepherdr bridge operation ${message.op}`);
@@ -5,9 +5,9 @@ import { fileURLToPath } from "node:url";
5
5
  import type { HerdrConnection } from "./herdr-client.js";
6
6
  import type { RemoteMachineConfig } from "./machines-config.js";
7
7
  import type { AssistantReader } from "./session-reader.js";
8
- import type { HerdrEvent, LatestAssistant } from "./types.js";
8
+ import type { HerdrEvent, LatestAssistant, SessionView } from "./types.js";
9
9
 
10
- const BRIDGE_VERSION = 1;
10
+ const BRIDGE_VERSION = 3;
11
11
  const REMOTE_HELPER = "~/.pi/agent/shepherdr.mjs";
12
12
  const MAX_FRAME_BYTES = 8 * 1024 * 1024;
13
13
  const MAX_DIAGNOSTIC_BYTES = 8 * 1024;
@@ -230,9 +230,15 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
230
230
  }
231
231
 
232
232
  async latest(path?: string): Promise<LatestAssistant | undefined> {
233
- return (await this.call({ op: "latest", path })) as
234
- | LatestAssistant
235
- | undefined;
233
+ return (await this.view(path)).assistant;
234
+ }
235
+
236
+ async view(path?: string): Promise<SessionView> {
237
+ return (await this.call({ op: "view", path })) as SessionView;
238
+ }
239
+
240
+ async keybindings(): Promise<Record<string, unknown>> {
241
+ return (await this.call({ op: "keybindings" })) as Record<string, unknown>;
236
242
  }
237
243
 
238
244
  async directory(