@howaboua/pi-shepherdr 0.2.6 → 0.2.8

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.2.8
4
+
5
+ - Agent profiles now control delegation waiting and shared context.
6
+
7
+ - Removed reviewer-name blocking rules. Optional profile `blocking` forces blocking or asynchronous spawns, and help and list report the configured policy with the profile description.
8
+ - Added `share_context: false` for independent subagent notes and history. Existing installed profiles remain unchanged.
9
+
10
+ ## 0.2.7
11
+
12
+ - Added opt-in shared notes and history for spawned agents with Pi Codex Conversion.
13
+
14
+ - New and nested workers receive distinct, persistent context identities before their first task.
15
+ - Local and Tree context stays in its owning sessions and routes through live controllers and existing SSH connections. Remote storage sharing requires the same Codex account.
16
+ - Sharing follows **Share subagent context** under `/codex context` and affects new spawns only. Existing agents and ordinary delegation remain unchanged.
17
+ - Wakeups of existing agents now say “Continue, unless awaiting for user approval.” Fresh-agent startup is unchanged.
18
+ - Fixed spawned agents dispatching before their persistent Pi session is registered. Profiles using `--no-session` now fail before creating a tab or workspace.
19
+ - Delegated tasks now guide workers to finish or report blockage with an assistant reply, reserving peer messages for useful mid-run updates rather than waiting or taking over orchestration.
20
+ - Peer messages now reach the receiving agent's active voice as brief updates, alongside completion reports. Task dispatches and slash commands are not announced.
21
+
3
22
  ## 0.2.6
4
23
 
5
24
  - Fixed exact Ask answer confirmation and retry reconciliation without resending input.
package/README.md CHANGED
@@ -38,7 +38,7 @@ Shepherdr reads Herdr's existing machine profiles and connects enabled profiles
38
38
 
39
39
  Profiles belong to the host running Pi, not the machine displaying its terminal. Omit `machine` for local agent calls. `list` and `find` search all machines unless filtered. Explicit `local` also means the host running Pi. For remote calls, use the opaque profile ID returned by `list`, not its label or hostname. Renaming a profile changes its label, not its routing identity.
40
40
 
41
- Remote machines connect over noninteractive SSH. The target needs `node` on its SSH PATH, Herdr 0.9 or newer, the Herdr Pi integration and a running Herdr session. Shepherdr installs one helper at `~/.pi/agent/shepherdr.mjs` on each remote, runs it only for the connection lifetime and leaves no remote daemon behind. Herdr's multi-machine UI does not expose a cross-machine automation socket, so Shepherdr still owns its remote transport and Pi transcript reads.
41
+ Remote machines connect over noninteractive SSH. The target needs `node` on its SSH PATH, Herdr 0.9 or newer, the Herdr Pi integration and a running Herdr session. Shepherdr installs managed transport helpers under `~/.pi/agent` on each remote, runs them only for the connection lifetime and leaves no remote daemon behind. Herdr's multi-machine UI does not expose a cross-machine automation socket, so Shepherdr still owns its remote transport and Pi transcript reads.
42
42
 
43
43
  ### Migrating from separate Shepherdr machines
44
44
 
@@ -61,7 +61,7 @@ Call the `agents` tool with `action: "help"` before first use, then send flat re
61
61
  | `watch` | Push future settlement from an existing Pi agent |
62
62
  | `unwatch` | Stop reporting an agent |
63
63
 
64
- `spawn` and `assign` block by default. Set `blocking: false` when the controller should continue other work immediately. Task completion and blockage are then delivered automatically.
64
+ `spawn` and `assign` block by default. Set `blocking: false` when the controller should continue other work immediately. A profile's `blocking` setting overrides the call for `spawn`. Task completion and blockage are then delivered automatically.
65
65
 
66
66
  `answer` requires the pending `ask_id` from `read` or a blocked report. It returns `accepted` only when that exact Ask persisted the supplied responses; an accepted retry sends no input.
67
67
 
@@ -69,8 +69,6 @@ Questions, status updates and replies use `send`. It returns after submission, d
69
69
 
70
70
  Automatic delegation watches end when the task finishes or fails. Blocked tasks stay watched until resolved. Only an explicit `watch` keeps reporting subsequent work until `unwatch`. Sending an update to your worker preserves its existing task watch without replacing the task.
71
71
 
72
- Reviewer spawns always block, even when `blocking: false` is supplied. The controller waits for the review before continuing work on its scope.
73
-
74
72
  Every `spawn` needs an `agent_type` and a concise two- or three-word `label`. The label names both the Herdr tab and Pi session; the routing `name` remains optional and is derived from it when omitted.
75
73
 
76
74
  Cancelling a blocking call does not kill its worker. The waiter detaches and the eventual result returns through normal asynchronous delivery.
@@ -85,6 +83,18 @@ Idle messages start a prepared user turn. Messages arriving during a run use ste
85
83
 
86
84
  For `answer` inside Code or Notebook Mode, update Pi Ask on workers together with Shepherdr on controllers.
87
85
 
86
+ ## Shared notes and history
87
+
88
+ With Pi Codex Conversion 3.0.40 or newer and notes-based continuity, enable **Share subagent context** under `/codex context` in the controller. It is off by default. Shared `spawn` gives each child a unique context identity before its first turn; `contextAgent` in the result identifies its notes and history. Shared nested spawns stay in the same family. Turning sharing off affects new spawns only; existing identity survives resume. `assign` and independently started agents remain unchanged. Older compatible Conversion versions keep ordinary delegation without sharing.
89
+
90
+ Set `"share_context": false` in a profile to keep its new workers' notes and history independent even when controller sharing is enabled. Omission or `true` follows the controller setting, never turns sharing on itself. This separates context, not filesystem permissions or information included in the task.
91
+
92
+ Pi creates each worker session normally. The worker records its shared identity before Shepherdr delivers the first task; no pre-created session file or launch override is needed.
93
+
94
+ Remote sharing requires Remote storage and the same Codex account on both ends. Local and Tree route through the owning Pi sessions and existing SSH connections. Those owners and intermediate controllers must be running; unavailable routes fail explicitly. Resume the owner and use `/herdr connect` after a connection loss. No note store is copied or silently substituted.
95
+
96
+ Both extensions work independently. A target without active context support still starts, with a warning that its context is not shared. A conflicting storage mode or account rejects the shared spawn before task delivery. Profiles that select or resume an existing session cannot participate in shared `spawn`; use `assign` instead.
97
+
88
98
  ## Profiles
89
99
 
90
100
  On first load, Shepherdr installs three editable profiles:
@@ -116,6 +126,13 @@ That directory is authoritative after initialization. Edit a profile to change i
116
126
 
117
127
  `prompt` is read as system-prompt text. An optional `prepare` module may export `prepare({ cwd, message, base, local })` and return the worker message. Preparation runs on the controlling machine before dispatch; `local` says whether that machine also hosts the worker.
118
128
 
129
+ Optional profile settings:
130
+
131
+ - `blocking`: `true` forces blocking spawns, `false` forces asynchronous spawns. Omission respects the call's `blocking` value, which defaults to `true`. This does not affect `assign` to existing agents.
132
+ - `share_context`: `false` opts new spawns out of shared notes and history. Omission or `true` follows the controller setting.
133
+
134
+ `help` and `list` expose each profile's description and configured settings. Profile names carry no blocking policy. The bundled reviewer profile sets `"blocking": true`; change it to `false` to force asynchronous review, or remove it to choose per call. Existing installed profiles are never overwritten. An existing reviewer without `blocking` now respects the call like any other profile.
135
+
119
136
  ## Advanced Herdr control
120
137
 
121
138
  Ordinary delegation stays inside `agents`. For workspace, tab, pane, process, focus, layout or raw-terminal operations, run `herdr --skill` and follow the installed Herdr skill. Shepherdr does not duplicate those controls.
package/index.ts CHANGED
@@ -8,6 +8,7 @@ import { AgentFleet } from "./src/fleet.js";
8
8
  import { registerAgentEventRenderer } from "./src/messages.js";
9
9
  import { registerPeerInbox } from "./src/peer-inbox.js";
10
10
  import { installAgentProfiles } from "./src/profiles.js";
11
+ import { registerSharedAgentContext } from "./src/shared-context.js";
11
12
 
12
13
  const CODE_MODE_PACKAGE = "@howaboua/pi-codex-conversion";
13
14
  const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
@@ -20,7 +21,8 @@ export default async function shepherdrExtension(
20
21
  await registerDeveloperDelivery(pi);
21
22
  registerPeerInbox(pi);
22
23
  const fleet = new AgentFleet(pi);
23
- const tool = createAgentsTool(fleet);
24
+ const sharedContext = await registerSharedAgentContext(pi, fleet);
25
+ const tool = createAgentsTool(fleet, sharedContext);
24
26
 
25
27
  registerAgentEventRenderer(pi);
26
28
  pi.registerTool(tool);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "description": "Persistent blocking and asynchronous Pi agents through Herdr.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -43,7 +43,7 @@
43
43
  "pack:dry": "npm pack --dry-run"
44
44
  },
45
45
  "peerDependencies": {
46
- "@howaboua/pi-codex-conversion": ">=3.0.38",
46
+ "@howaboua/pi-codex-conversion": ">=3.0.40",
47
47
  "@earendil-works/pi-ai": ">=0.84.3",
48
48
  "@earendil-works/pi-coding-agent": ">=0.84.4",
49
49
  "@earendil-works/pi-tui": ">=0.84.3",
@@ -55,11 +55,11 @@
55
55
  }
56
56
  },
57
57
  "devDependencies": {
58
- "@howaboua/pi-codex-conversion": "3.0.38",
58
+ "@howaboua/pi-codex-conversion": "3.0.40",
59
59
  "@biomejs/biome": "^2.5.10",
60
- "@earendil-works/pi-ai": "0.87.0",
61
- "@earendil-works/pi-coding-agent": "0.87.0",
62
- "@earendil-works/pi-tui": "0.87.0",
60
+ "@earendil-works/pi-ai": "0.99.1",
61
+ "@earendil-works/pi-coding-agent": "0.99.1",
62
+ "@earendil-works/pi-tui": "0.99.1",
63
63
  "@types/node": "^26.2.0",
64
64
  "typebox": "1.3.18",
65
65
  "typescript": "^7.0.2"
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "description": "Read-only review",
3
+ "blocking": true,
3
4
  "model": "openai-codex/gpt-6-luna",
4
5
  "thinking": "xhigh",
5
6
  "prompt": "prompt.md",
@@ -2,6 +2,7 @@ import { StringEnum, Type } from "@earendil-works/pi-ai";
2
2
  import type { Static } from "typebox";
3
3
  import { Check } from "typebox/value";
4
4
  import { START_PLACEMENTS } from "./launch.js";
5
+ import { loadAgentProfileBlocking } from "./profiles.js";
5
6
 
6
7
  const ACTIONS = [
7
8
  "help",
@@ -75,11 +76,11 @@ const AgentsRequest = Type.Object(
75
76
  message: Type.Optional(
76
77
  Type.String({ description: "Initial task or follow-up" }),
77
78
  ),
78
- base: Type.Optional(Type.String({ description: "Reviewer base branch" })),
79
+ base: Type.Optional(Type.String({ description: "Review base branch" })),
79
80
  blocking: Type.Optional(
80
81
  Type.Boolean({
81
82
  description:
82
- "Delegation only; defaults true. False pushes task settlement later",
83
+ "Delegation only; profile policy overrides spawn; otherwise defaults true",
83
84
  }),
84
85
  ),
85
86
  query: Type.Optional(Type.String()),
@@ -158,7 +159,12 @@ export function isBlockingAgentsCall(input: unknown): boolean {
158
159
  try {
159
160
  const value = parseAgentsRequest(input);
160
161
  if (value.action === "spawn")
161
- return shouldBlockAgentSpawn(value.agent_type, value.blocking);
162
+ return shouldBlockAgentSpawn(
163
+ loadAgentProfileBlocking(
164
+ requiredAgentField(value.agent_type, "agent_type"),
165
+ ),
166
+ value.blocking,
167
+ );
162
168
  return BLOCKING_ACTIONS.has(value.action) && value.blocking !== false;
163
169
  } catch {
164
170
  return false;
@@ -166,8 +172,8 @@ export function isBlockingAgentsCall(input: unknown): boolean {
166
172
  }
167
173
 
168
174
  export function shouldBlockAgentSpawn(
169
- agentType: string | undefined,
175
+ profileBlocking: boolean | undefined,
170
176
  blocking: boolean | undefined,
171
177
  ): boolean {
172
- return agentType?.trim() === "reviewer" || blocking !== false;
178
+ return profileBlocking ?? blocking ?? true;
173
179
  }
@@ -1,11 +1,28 @@
1
1
  import type { AgentsParams, READ_SOURCES } from "./agents-contract.js";
2
2
  import type { AgentFleet, ConnectedMachine } from "./fleet.js";
3
- import { loadAgentProfiles } from "./profiles.js";
3
+ import { type AgentProfile, loadAgentProfiles } from "./profiles.js";
4
4
  import type { AgentStatus, PaneInfo, SessionSnapshot } from "./types.js";
5
5
 
6
6
  const MAX_LIST_ITEMS = 30;
7
7
  const MAX_TERMINAL_READ_CHARS = 36_000;
8
8
 
9
+ function describeProfiles(profiles: Map<string, AgentProfile>) {
10
+ return Object.fromEntries(
11
+ [...profiles].map(([name, profile]) => [
12
+ name,
13
+ {
14
+ description: profile.description,
15
+ ...(profile.blocking === undefined
16
+ ? {}
17
+ : { blocking: profile.blocking }),
18
+ ...(profile.shareContext === undefined
19
+ ? {}
20
+ : { share_context: profile.shareContext }),
21
+ },
22
+ ]),
23
+ );
24
+ }
25
+
9
26
  export async function agentsHelp(): Promise<Record<string, unknown>> {
10
27
  const profiles = await loadAgentProfiles();
11
28
  return {
@@ -32,7 +49,9 @@ export async function agentsHelp(): Promise<Record<string, unknown>> {
32
49
  send: "Peer questions, updates, replies; submission only, no wait or watch",
33
50
  assign: "Delegate a task to an existing agent",
34
51
  blocking:
35
- "spawn/assign default true; false pushes task settlement; never poll. Reviewer spawns always block; await review before working its scope",
52
+ "spawn/assign default true; profile blocking overrides spawn; false pushes task settlement; never poll",
53
+ share_context:
54
+ "Profile false isolates notes/history; otherwise follows controller sharing setting",
36
55
  watch:
37
56
  "Explicit watch persists until unwatch; automatic task watches end on finish/failure, not blockage",
38
57
  prompt:
@@ -47,9 +66,7 @@ export async function agentsHelp(): Promise<Record<string, unknown>> {
47
66
  }
48
67
  : {}),
49
68
  },
50
- profiles: Object.fromEntries(
51
- [...profiles].map(([name, profile]) => [name, profile.description]),
52
- ),
69
+ profiles: describeProfiles(profiles),
53
70
  advanced: "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
54
71
  };
55
72
  }
@@ -137,9 +154,7 @@ export async function listFleetAgents(
137
154
  })),
138
155
  );
139
156
  return {
140
- profiles: Object.fromEntries(
141
- [...profiles].map(([name, profile]) => [name, profile.description]),
142
- ),
157
+ profiles: describeProfiles(profiles),
143
158
  machines: machines.map(
144
159
  ({
145
160
  snapshot: _snapshot,
@@ -1,4 +1,7 @@
1
- import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
1
+ import type {
2
+ AgentToolUpdateCallback,
3
+ ExtensionContext,
4
+ } from "@earendil-works/pi-coding-agent";
2
5
  import {
3
6
  type AgentsParams,
4
7
  requiredAgentField as required,
@@ -24,6 +27,7 @@ import {
24
27
  prepareProfileMessage,
25
28
  profileAgentArgs,
26
29
  } from "./profiles.js";
30
+ import type { SharedAgentContext } from "./shared-context.js";
27
31
 
28
32
  function agentLabel(value: string | undefined): string {
29
33
  const label = required(value, "label");
@@ -40,6 +44,8 @@ export async function spawnAgent(
40
44
  params: AgentsParams,
41
45
  signal: AbortSignal,
42
46
  onUpdate: AgentToolUpdateCallback<Record<string, unknown>>,
47
+ sharedContext: SharedAgentContext,
48
+ ctx: ExtensionContext,
43
49
  ) {
44
50
  const profiles = await loadAgentProfiles();
45
51
  const profileName = required(params.agent_type, "agent_type");
@@ -91,29 +97,34 @@ export async function spawnAgent(
91
97
  "task",
92
98
  );
93
99
  if (input.startsWith("/") && message !== input)
94
- attributedMessage.context = message;
100
+ attributedMessage.context = [attributedMessage.context, message]
101
+ .filter(Boolean)
102
+ .join("\n\n");
95
103
  reportProgress(onUpdate, `Spawning ${label}`, {
96
104
  machine: runtime.machine,
97
105
  name,
98
106
  profile: profile.name,
99
107
  status: "starting",
100
108
  });
109
+ const agentArgs = profileAgentArgs(profile, { targetLocal: runtime.local });
110
+ const sharing =
111
+ profile.shareContext === false
112
+ ? undefined
113
+ : await sharedContext.prepare(ctx, runtime, name, agentArgs);
101
114
  const started = await startAgent(
102
115
  runtime.client,
103
116
  startParams,
104
117
  runtime.fallbackCwd,
105
118
  runtime.resolveDirectory,
106
- {
107
- agentArgs: profileAgentArgs(profile, {
108
- targetLocal: runtime.local,
109
- }),
110
- },
119
+ { agentArgs },
111
120
  );
112
121
  let promptSubmissionStarted = false;
113
122
  let promptAccepted = false;
114
123
  let dispatch;
115
- const blocking = shouldBlockAgentSpawn(profile.name, params.blocking);
124
+ let shared: { agentName?: string; warning?: string } | undefined;
125
+ const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
116
126
  try {
127
+ shared = await sharing?.accept(started.agent);
117
128
  dispatch = await dispatchAgentWork(
118
129
  runtime,
119
130
  started.agent,
@@ -142,27 +153,30 @@ export async function spawnAgent(
142
153
  throw error;
143
154
  }
144
155
  return toolResult(
145
- dispatch.command
146
- ? {
147
- spawned: true,
148
- commandSubmitted: true,
149
- machine: runtime.machine,
150
- target: started.id,
151
- name,
152
- }
153
- : dispatch.settlement
156
+ {
157
+ ...(shared?.agentName ? { contextAgent: shared.agentName } : {}),
158
+ ...(dispatch.command
154
159
  ? {
155
160
  spawned: true,
156
- ...settlementResult(runtime.machine, dispatch.settlement),
157
- }
158
- : {
159
- spawned: true,
161
+ commandSubmitted: true,
160
162
  machine: runtime.machine,
161
163
  target: started.id,
162
164
  name,
163
- status: "working",
164
- next: "Completion or blockage will be delivered automatically; do not poll",
165
- },
166
- dispatch.warning,
165
+ }
166
+ : dispatch.settlement
167
+ ? {
168
+ spawned: true,
169
+ ...settlementResult(runtime.machine, dispatch.settlement),
170
+ }
171
+ : {
172
+ spawned: true,
173
+ machine: runtime.machine,
174
+ target: started.id,
175
+ name,
176
+ status: "working",
177
+ next: "Completion or blockage will be delivered automatically; do not poll",
178
+ }),
179
+ },
180
+ [dispatch.warning, shared?.warning].filter(Boolean).join("\n") || undefined,
167
181
  );
168
182
  }
@@ -23,21 +23,19 @@ import {
23
23
  import type { AgentFleet } from "./fleet.js";
24
24
  import { resolvePiAgent } from "./herdr.js";
25
25
  import { attributeAgentPrompt, modelAsk } from "./messages.js";
26
+ import type { SharedAgentContext } from "./shared-context.js";
26
27
 
27
- export function createAgentsTool(fleet: AgentFleet) {
28
+ export function createAgentsTool(
29
+ fleet: AgentFleet,
30
+ sharedContext: SharedAgentContext,
31
+ ) {
28
32
  return defineTool({
29
33
  name: "agents",
30
34
  label: "Shepherdr",
31
35
  description: "Delegate to persistent agents; call help first, alone",
32
36
  parameters: AgentsParameters,
33
37
  executionMode: "sequential",
34
- async execute(
35
- _toolCallId,
36
- input: AgentsToolParams,
37
- signal,
38
- onUpdate,
39
- _ctx,
40
- ) {
38
+ async execute(_toolCallId, input: AgentsToolParams, signal, onUpdate, ctx) {
41
39
  const params = parseAgentsRequest(input);
42
40
  const executionSignal = signal ?? new AbortController().signal;
43
41
  const update = onUpdate ?? (() => undefined);
@@ -53,7 +51,15 @@ export function createAgentsTool(fleet: AgentFleet) {
53
51
 
54
52
  const runtime = fleet.connected(params.machine);
55
53
  if (params.action === "spawn") {
56
- return spawnAgent(fleet, runtime, params, executionSignal, update);
54
+ return spawnAgent(
55
+ fleet,
56
+ runtime,
57
+ params,
58
+ executionSignal,
59
+ update,
60
+ sharedContext,
61
+ ctx,
62
+ );
57
63
  }
58
64
 
59
65
  const target = required(params.target, "target");
package/src/delivery.ts CHANGED
@@ -91,16 +91,27 @@ export async function registerDeveloperDelivery(
91
91
 
92
92
  export function startPreparedIdleTurn(
93
93
  pi: ExtensionAPI,
94
- ctx: Pick<ExtensionContext, "ui">,
94
+ ctx: Pick<ExtensionContext, "ui" | "sessionManager">,
95
95
  start?: () => void,
96
96
  ): void {
97
+ // Session history survives tree cuts; a new active branch is not a fresh agent.
98
+ const prompt =
99
+ !start &&
100
+ ctx.sessionManager
101
+ .getEntries()
102
+ .some(
103
+ (entry) =>
104
+ entry.type === "message" && entry.message.role === "assistant",
105
+ )
106
+ ? "Continue, unless awaiting for user approval."
107
+ : "Continue.";
97
108
  if (start) {
98
109
  if (preparedPrompts.get(pi)?.(pi, start)) return;
99
110
  if (preparedKickoffs.has(pi) && !preparedPrompts.has(pi))
100
111
  throw new Error(
101
112
  "Update Pi Codex Conversion and reload before sending slash commands",
102
113
  );
103
- } else if (preparedKickoffs.get(pi)?.(pi, ctx)) return;
114
+ } else if (preparedKickoffs.get(pi)?.(pi, ctx, prompt)) return;
104
115
  if (fallbackKickoffs.has(pi)) {
105
116
  if (start)
106
117
  throw new Error(
@@ -118,7 +129,7 @@ export function startPreparedIdleTurn(
118
129
  fallbackKickoffs.set(pi, "preparing");
119
130
  try {
120
131
  if (start) start();
121
- else pi.sendUserMessage("Continue.", { deliverAs: "steer" });
132
+ else pi.sendUserMessage(prompt, { deliverAs: "steer" });
122
133
  } catch (error) {
123
134
  fallbackKickoffs.delete(pi);
124
135
  throw error;
package/src/fleet.ts CHANGED
@@ -27,6 +27,7 @@ interface Runtime {
27
27
  attempting?: boolean;
28
28
  client?: HerdrConnection;
29
29
  config?: SshMachine;
30
+ contextRelayError?: string;
30
31
  local: boolean;
31
32
  monitor?: AgentMonitor;
32
33
  monitoringIssue?: MonitoringIssue;
@@ -106,6 +107,22 @@ function groupSaved(values: unknown[]): Map<string, unknown[]> {
106
107
  }
107
108
 
108
109
  export class AgentFleet {
110
+ private contextRelay:
111
+ | ((
112
+ ctx: ExtensionContext,
113
+ request: unknown,
114
+ signal: AbortSignal,
115
+ ) => Promise<unknown>)
116
+ | undefined;
117
+ setContextRelay(
118
+ handler: (
119
+ ctx: ExtensionContext,
120
+ request: unknown,
121
+ signal: AbortSignal,
122
+ ) => Promise<unknown>,
123
+ ): void {
124
+ this.contextRelay = handler;
125
+ }
109
126
  private context: ExtensionContext | undefined;
110
127
  private generation = 0;
111
128
  private readonly pi: ExtensionAPI;
@@ -342,11 +359,14 @@ export class AgentFleet {
342
359
  const runtime = this.runtimes.get(target);
343
360
  if (!runtime)
344
361
  throw new Error(`unknown Herdr machine ${JSON.stringify(target)}`);
345
- if (runtime.status === "connected" && runtime.monitoringIssue) {
362
+ if (
363
+ runtime.status === "connected" &&
364
+ (runtime.monitoringIssue || runtime.contextRelayError)
365
+ ) {
346
366
  if (runtime.attempting)
347
- return `Already retrying monitoring on ${target}`;
348
- void this.retryMonitoring(target, runtime);
349
- return `Retrying monitoring on ${target}`;
367
+ return `Already retrying connection setup on ${target}`;
368
+ void this.retrySetup(target, runtime);
369
+ return `Retrying connection setup on ${target}`;
350
370
  }
351
371
  if (runtime.local) {
352
372
  return `${target} is the local machine and is already connected`;
@@ -364,11 +384,10 @@ export class AgentFleet {
364
384
  const retries = [...this.runtimes.entries()].filter(
365
385
  ([, runtime]) =>
366
386
  runtime.status === "connected" &&
367
- runtime.monitoringIssue &&
387
+ (runtime.monitoringIssue || runtime.contextRelayError) &&
368
388
  !runtime.attempting,
369
389
  );
370
- for (const [name, runtime] of retries)
371
- void this.retryMonitoring(name, runtime);
390
+ for (const [name, runtime] of retries) void this.retrySetup(name, runtime);
372
391
  const names = [...this.runtimes.entries()]
373
392
  .filter(
374
393
  ([, runtime]) =>
@@ -383,7 +402,7 @@ export class AgentFleet {
383
402
  if (names.length > 0 || retries.length > 0) {
384
403
  return [
385
404
  retries.length > 0
386
- ? `Retrying monitoring on ${retries.map(([name]) => name).join(", ")}`
405
+ ? `Retrying connection setup on ${retries.map(([name]) => name).join(", ")}`
387
406
  : "",
388
407
  names.length > 0 ? `Connecting to ${names.join(", ")}` : "",
389
408
  ]
@@ -473,14 +492,49 @@ export class AgentFleet {
473
492
  });
474
493
  }
475
494
 
476
- private async retryMonitoring(name: string, runtime: Runtime): Promise<void> {
495
+ private async prepareContextRelay(
496
+ name: string,
497
+ runtime: Runtime,
498
+ client: RemoteHerdrClient,
499
+ ctx: ExtensionContext,
500
+ ): Promise<void> {
501
+ if (!this.contextRelay) return;
502
+ try {
503
+ await client.startContextRelay(
504
+ ctx.sessionManager.getSessionId(),
505
+ name,
506
+ (request, signal) => this.contextRelay!(ctx, request, signal),
507
+ );
508
+ if (this.context !== ctx || this.runtimes.get(name) !== runtime) return;
509
+ delete runtime.contextRelayError;
510
+ } catch (error) {
511
+ if (this.context !== ctx || this.runtimes.get(name) !== runtime) return;
512
+ runtime.contextRelayError = errorMessage(error);
513
+ ctx.ui.notify(
514
+ `Context sharing unavailable on ${name}: ${runtime.contextRelayError}\nRun /herdr connect ${name} to retry sharing.`,
515
+ "warning",
516
+ );
517
+ }
518
+ }
519
+
520
+ private async retrySetup(name: string, runtime: Runtime): Promise<void> {
477
521
  const monitor = runtime.monitor;
478
522
  const ctx = this.context;
479
523
  const generation = this.generation;
480
524
  if (!monitor || !ctx || runtime.attempting) return;
481
525
  runtime.attempting = true;
482
526
  try {
483
- await monitor.retryMonitoring();
527
+ if (
528
+ runtime.contextRelayError &&
529
+ runtime.client instanceof RemoteHerdrClient
530
+ )
531
+ await this.prepareContextRelay(name, runtime, runtime.client, ctx);
532
+ if (
533
+ this.isCurrent(generation, ctx) &&
534
+ this.runtimes.get(name) === runtime &&
535
+ runtime.monitoringIssue
536
+ )
537
+ await monitor.retryMonitoring();
484
538
  } catch (error) {
485
539
  if (
486
540
  this.isCurrent(generation, ctx) &&
@@ -526,6 +580,7 @@ export class AgentFleet {
526
580
  if (runtime.client === client)
527
581
  this.disconnected(name, runtime, error.message);
528
582
  });
583
+ await this.prepareContextRelay(name, runtime, client, ctx);
529
584
  if (
530
585
  !this.isCurrent(generation, ctx) ||
531
586
  this.runtimes.get(name) !== runtime
@@ -596,6 +651,7 @@ export class AgentFleet {
596
651
  runtime.monitor?.deactivate();
597
652
  if (runtime.client instanceof RemoteHerdrClient) runtime.client.close();
598
653
  delete runtime.client;
654
+ delete runtime.contextRelayError;
599
655
  delete runtime.monitoringIssue;
600
656
  runtime.status = "unavailable";
601
657
  delete runtime.attempting;
@@ -1,4 +1,5 @@
1
1
  import { createConnection } from "node:net";
2
+ import { requestContext } from "./remote/shepherdr-context.mjs";
2
3
  import { sendPeerMessage } from "./remote/shepherdr-peer.mjs";
3
4
  import type {
4
5
  HerdrEvent,
@@ -55,6 +56,12 @@ export function isHerdrErrorCode(error: unknown, code: string): boolean {
55
56
  }
56
57
 
57
58
  export interface HerdrConnection {
59
+ requestContext(
60
+ path: string,
61
+ request: unknown,
62
+ signal?: AbortSignal,
63
+ ): Promise<unknown>;
64
+ contextRelayPath(): string;
58
65
  request<T>(method: string, params?: object, timeoutMs?: number): Promise<T>;
59
66
  sendMessage(agent: PaneInfo, message: PeerMessage): Promise<PeerDelivery>;
60
67
  subscribe(
@@ -67,6 +74,16 @@ export interface HerdrConnection {
67
74
 
68
75
  export class HerdrClient implements HerdrConnection {
69
76
  readonly socketPath: string;
77
+ requestContext(
78
+ path: string,
79
+ request: unknown,
80
+ signal?: AbortSignal,
81
+ ): Promise<unknown> {
82
+ return requestContext(path, request, signal);
83
+ }
84
+ contextRelayPath(): string {
85
+ throw new Error("Local context routes use the controller session");
86
+ }
70
87
 
71
88
  constructor(socketPath = process.env["HERDR_SOCKET_PATH"]) {
72
89
  if (!socketPath) {