pi-herdsman 0.22.2 → 0.23.0

package/dist/integrations/pi-codex-context-sharing.js

@@ -0,0 +1,42 @@
+// extension/integrations/pi-codex-context-sharing.ts
+import { connectCodexContextSharing } from "@howaboua/pi-codex-conversion/context-sharing";
+var BOOTSTRAP_EVENT = "pi-herdsman:managed-agent-bootstrap";
+var PARTICIPANT_ID = "pi-codex/context-sharing";
+function register(pi) {
+  const connection = connectCodexContextSharing(pi);
+  const offBootstrap = pi.events.on(BOOTSTRAP_EVENT, (value) => {
+    const event = value;
+    if (event?.protocol !== 1) return;
+    if (event.phase === "prepare") {
+      event.register(PARTICIPANT_ID, async () => {
+        const service = connection.service;
+        if (!service?.canCreateChild(event.context)) return void 0;
+        const identity = service.describe(event.context);
+        if (identity?.storage !== "remote") return void 0;
+        const { binding, adopt } = await service.createChild(event.context, {
+          name: event.agent
+        });
+        return {
+          payload: JSON.stringify(binding),
+          commit: adopt
+        };
+      });
+      return;
+    }
+    if (event.participant?.id !== PARTICIPANT_ID) return;
+    event.accept(async () => {
+      const service = connection.service;
+      if (!service)
+        throw new Error("Pi Codex Conversion context sharing is unavailable");
+      await service.bind(event.context, JSON.parse(event.participant.payload));
+    });
+  });
+  pi.on("session_shutdown", () => {
+    offBootstrap();
+    connection.dispose();
+  });
+}
+export {
+  register as default
+};
+//# sourceMappingURL=pi-codex-context-sharing.js.map

package/dist/integrations/pi-codex-context-sharing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../extension/integrations/pi-codex-context-sharing.ts"],
+  "sourcesContent": ["import type {\n  ExtensionAPI,\n  ExtensionContext,\n} from \"@earendil-works/pi-coding-agent\";\nimport { connectCodexContextSharing } from \"@howaboua/pi-codex-conversion/context-sharing\";\n\nconst BOOTSTRAP_EVENT = \"pi-herdsman:managed-agent-bootstrap\";\nconst PARTICIPANT_ID = \"pi-codex/context-sharing\";\n\ntype Preparation = {\n  payload: string;\n  commit?: () => void | Promise<void>;\n};\n\ntype PrepareEvent = {\n  protocol: 1;\n  phase: \"prepare\";\n  context: ExtensionContext;\n  agent: string;\n  register(\n    id: string,\n    prepare: () => Preparation | undefined | Promise<Preparation | undefined>,\n  ): void;\n};\n\ntype InitializeEvent = {\n  protocol: 1;\n  phase: \"initialize\";\n  context: ExtensionContext;\n  agent: string;\n  participant: {\n    id: string;\n    payload: string;\n  };\n  accept(initialize: () => void | Promise<void>): void;\n};\n\ntype BootstrapEvent = PrepareEvent | InitializeEvent;\n\nexport default function register(pi: ExtensionAPI): void {\n  const connection = connectCodexContextSharing(pi);\n\n  const offBootstrap = pi.events.on(BOOTSTRAP_EVENT, (value) => {\n    const event = value as BootstrapEvent;\n    if (event?.protocol !== 1) return;\n\n    if (event.phase === \"prepare\") {\n      event.register(PARTICIPANT_ID, async () => {\n        const service = connection.service;\n        if (!service?.canCreateChild(event.context)) return undefined;\n\n        const identity = service.describe(event.context);\n        if (identity?.storage !== \"remote\") return undefined;\n\n        const { binding, adopt } = await service.createChild(event.context, {\n          name: event.agent,\n        });\n\n        return {\n          payload: JSON.stringify(binding),\n          commit: adopt,\n        };\n      });\n      return;\n    }\n\n    if (event.participant?.id !== PARTICIPANT_ID) return;\n\n    event.accept(async () => {\n      const service = connection.service;\n      if (!service)\n        throw new Error(\"Pi Codex Conversion context sharing is unavailable\");\n\n      await service.bind(event.context, JSON.parse(event.participant.payload));\n    });\n  });\n\n  pi.on(\"session_shutdown\", () => {\n    offBootstrap();\n    connection.dispose();\n  });\n}\n"],
+  "mappings": ";AAIA,SAAS,kCAAkC;AAE3C,IAAM,kBAAkB;AACxB,IAAM,iBAAiB;AAgCR,SAAR,SAA0B,IAAwB;AACvD,QAAM,aAAa,2BAA2B,EAAE;AAEhD,QAAM,eAAe,GAAG,OAAO,GAAG,iBAAiB,CAAC,UAAU;AAC5D,UAAM,QAAQ;AACd,QAAI,OAAO,aAAa,EAAG;AAE3B,QAAI,MAAM,UAAU,WAAW;AAC7B,YAAM,SAAS,gBAAgB,YAAY;AACzC,cAAM,UAAU,WAAW;AAC3B,YAAI,CAAC,SAAS,eAAe,MAAM,OAAO,EAAG,QAAO;AAEpD,cAAM,WAAW,QAAQ,SAAS,MAAM,OAAO;AAC/C,YAAI,UAAU,YAAY,SAAU,QAAO;AAE3C,cAAM,EAAE,SAAS,MAAM,IAAI,MAAM,QAAQ,YAAY,MAAM,SAAS;AAAA,UAClE,MAAM,MAAM;AAAA,QACd,CAAC;AAED,eAAO;AAAA,UACL,SAAS,KAAK,UAAU,OAAO;AAAA,UAC/B,QAAQ;AAAA,QACV;AAAA,MACF,CAAC;AACD;AAAA,IACF;AAEA,QAAI,MAAM,aAAa,OAAO,eAAgB;AAE9C,UAAM,OAAO,YAAY;AACvB,YAAM,UAAU,WAAW;AAC3B,UAAI,CAAC;AACH,cAAM,IAAI,MAAM,oDAAoD;AAEtE,YAAM,QAAQ,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,YAAY,OAAO,CAAC;AAAA,IACzE,CAAC;AAAA,EACH,CAAC;AAED,KAAG,GAAG,oBAAoB,MAAM;AAC9B,iBAAa;AACb,eAAW,QAAQ;AAAA,EACrB,CAAC;AACH;",
+  "names": []
+}

package/docs/guides/customizing-agents.md

@@ -362,3 +362,35 @@ session.
 - [Agent-definition schema](../reference/agent-definition-schema.md)
 - [`/agents` commands](../reference/commands.md)
 - [Agent definitions](agent-definitions.md)
+
+## Optional Pi Codex Conversion context sharing
+
+The Herdsman adapter for Pi Codex Conversion (PCC) is optional and supports
+Remote storage only. PCC's `shareSubagentContext` setting remains authoritative.
+Load the adapter in both the delegating controller and each participating fresh
+managed child; it is shipped at
+`dist/integrations/pi-codex-context-sharing.js` but is not loaded by default.
+For a normal npm Pi installation, reference it explicitly, for example:
+
+```text
+~/.pi/agent/npm/node_modules/pi-herdsman/dist/integrations/pi-codex-context-sharing.js
+```
+
+When a managed Agent definition uses `noExtensions: true`, list both PCC and the
+Herdsman adapter in that definition's `extensions`:
+
+```yaml
+---
+name: shared-worker
+noExtensions: true
+extensions:
+  - "~/.pi/agent/npm/node_modules/@howaboua/pi-codex-conversion/dist/index.js"
+  - "~/.pi/agent/npm/node_modules/pi-herdsman/dist/integrations/pi-codex-context-sharing.js"
+---
+```
+
+An explicit `tools` allowlist must independently permit the tools needed by the
+current PCC execution mode. The adapter does not modify tools or PCC execution
+mode; consult PCC for mode-specific requirements. PCC restores the saved
+context identity on continuation, so no adapter rebind is needed. Local and
+Tree storage are not supported because they require ongoing context routing.

package/docs/reference/agent.md

@@ -42,6 +42,52 @@ session.
 Each accepted definition delegation creates one agent generation for one
 assignment. The terminal result is delivered once and the agent is cleaned up.
 
+## Managed-agent bootstrap extension contract
+
+Extensions that are already loaded in both the delegating controller and a
+child may participate in fresh initialization through Pi's event bus channel
+`pi-herdsman:managed-agent-bootstrap`. The protocol version is `1`. This is
+available only for fresh `delegate_agent`; continuation never prepares,
+initializes, or commits bootstrap participants.
+
+During synchronous `prepare` event dispatch, listeners may synchronously call
+`register(id, prepare)`. IDs must be unique within a spawn and match
+`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$`. Herdsman then sequentially awaits each
+registered callback. Return `undefined` to opt out, or return an opaque string
+payload and optional parent-side commit callback:
+
+```ts
+pi.events.on("pi-herdsman:managed-agent-bootstrap", (value) => {
+  const event = value as any;
+  if (event.protocol !== 1 || event.phase !== "prepare") return;
+  event.register("example/child-state", async () => {
+    const prepared = await prepareChild(event.agent);
+    return {
+      payload: serialize(prepared),
+      commit: () => adoptChild(prepared),
+    };
+  });
+});
+```
+
+Preparation must be safe to abandon if launch fails; durable parent-side
+finalization belongs in the optional commit callback.
+
+For each prepared participant, the child receives an `initialize` event before
+Herdsman writes its normal `state.json` readiness record. Exactly one matching
+child extension must synchronously call `accept(initialize)` during event
+dispatch; Herdsman invokes and awaits that initializer before readiness. The
+participant owns payload serialization, compatibility, and interpretation.
+The aggregate bootstrap sidecar is limited to 64 KiB.
+
+A prepared participant without exactly one child initializer, a rejected or
+throwing initializer, a build/identity mismatch, invalid participant data, or
+an oversized payload fails startup. No task is delivered and the existing
+startup rollback applies. After normal child readiness and identity/integration
+validation, Herdsman awaits parent commit callbacks before it delivers the
+first assignment. Bootstrap storage is transient and removed before readiness.
+With no participant data, delegation follows its ordinary startup path.
+
 ## `continue_agent`
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "type": "module",
   "description": "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
   "license": "Apache-2.0",
@@ -75,12 +75,14 @@
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
+    "@howaboua/pi-codex-conversion": "^3.0.45",
     "typebox": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",
     "@earendil-works/pi-tui": "1.1.0",
+    "@howaboua/pi-codex-conversion": "3.0.45",
     "esbuild": "^0.28.2",
     "typebox": "^1.3.7"
   },
@@ -97,5 +99,10 @@
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependenciesMeta": {
+    "@howaboua/pi-codex-conversion": {
+      "optional": true
+    }
   }
 }