Squashed 'third_party/pi/' content from commit d981de122

git-subtree-dir: third_party/pi
git-subtree-split: d981de1229ef899957bbe968bc8dcda02a21f477

packages/coding-agent/examples/plugins/pi-example-plugin/README.md

@@ -0,0 +1,38 @@
+# `@earendil-works/pi-example-plugin`
+
+This package provides conventional `session` and `tui` Chord facets. The Session-worker facet provides a remote greeting service. The TUI facet contributes `/hello` and calls that service.
+
+The package needs no build script. Pi asks Chord to discover `src/session.ts` and `src/tui.ts`, builds both entries into its server-owned plugin cache, and sends the TUI artifact to clients.
+
+From the repository root:
+
+```bash
+PI_EXPERIMENTAL=1 ./pi-test.sh server \
+  -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
+```
+
+Alternatively, a client can select the plugin for the Session it creates or resumes on one local server:
+
+```bash
+PI_EXPERIMENTAL=1 ./pi-test.sh client \
+  -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
+```
+
+Repeat `-e` to select multiple plugin packages. Client paths are resolved locally and sent only to a Unix server; Radius clients cannot select server filesystem paths. The Session and matching TUI facets are stored with that Session, so later server generations and clients can resume it without plugin arguments. Other Sessions and their workers are unaffected. An active Session rejects a different package selection instead of being restarted.
+
+`server -e` establishes the server profile's default Session and TUI facets. Starting an explicit foreground server without `-e` clears that default. Client selection never changes the server's root facet generation.
+
+Run `/hello Armin` in the TUI. After editing a facet, run `/reload`. The server atomically rebuilds the package, reloads the attached Session-worker generation, updates the current TUI generation, and serves the new artifact to future clients.
+
+Package metadata can override or disable conventional entries:
+
+```json
+{
+  "chord": {
+    "facets": {
+      "session": "./src/worker.ts",
+      "tui": false
+    }
+  }
+}
+```

packages/coding-agent/examples/plugins/pi-example-plugin/package.json

@@ -0,0 +1,10 @@
+{
+	"name": "@earendil-works/pi-example-plugin",
+	"version": "1.0.0",
+	"private": true,
+	"type": "module",
+	"peerDependencies": {
+		"@earendil-works/chord": "^0.84.4",
+		"@earendil-works/pi-coding-agent": "^0.84.4"
+	}
+}

packages/coding-agent/examples/plugins/pi-example-plugin/src/contract.ts

@@ -0,0 +1,13 @@
+import { type Context, defineService, type ReplicatedState } from "@earendil-works/chord";
+
+export interface ExampleFacetReply {
+	readonly message: string;
+	readonly workerActivations: number;
+}
+
+export interface ExampleFacetService {
+	readonly workerActivations: ReplicatedState<{ count: number }>;
+	greet(input: { readonly name: string }, context: Context): Promise<ExampleFacetReply>;
+}
+
+export const ExampleFacetService = defineService<ExampleFacetService>("pi.example-plugin.greeting");

packages/coding-agent/examples/plugins/pi-example-plugin/src/session.ts

@@ -0,0 +1,23 @@
+import { defineFacet } from "@earendil-works/chord";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { ExampleFacetService } from "./contract.ts";
+
+export default defineFacet({
+	id: "@earendil-works/pi-example-plugin/session",
+	setup(env) {
+		const workerActivations = env.replicatedState({ count: 0 });
+		env.provide(ExampleFacetService, {
+			workerActivations,
+			async greet({ name }) {
+				return {
+					message: `Hello ${name} from the bundled Session worker facet!!!`,
+					workerActivations: workerActivations.value.count,
+				};
+			},
+		});
+		env.onActivate(() => {
+			workerActivations.state.count += 1;
+			workerActivations.publish(BACKGROUND_CONTEXT);
+		});
+	},
+});

packages/coding-agent/examples/plugins/pi-example-plugin/src/tui.ts

@@ -0,0 +1,31 @@
+import { defineFacet } from "@earendil-works/chord";
+import { AgentController, PresentationUI, SlashCommands } from "@earendil-works/pi-coding-agent/experimental/plugin";
+import { ExampleFacetService } from "./contract.ts";
+
+export default defineFacet({
+	id: "@earendil-works/pi-example-plugin/tui",
+	setup(env) {
+		const example = env.use(ExampleFacetService);
+		const commands = env.use(SlashCommands);
+		const controller = env.use(AgentController);
+		const ui = env.use(PresentationUI);
+		env.onActivate(() => {
+			env.own(
+				commands.replace({
+					name: "hello",
+					description: "Call the bundled Session worker facet",
+					argumentHint: "<name>",
+					async run(args, context) {
+						const message = args.length === 0 ? "from the TUI" : args;
+						const reply = await example.greet({ name: message }, context);
+						ui.showStatus(
+							`We got this: ${reply.message} Worker activations: ${reply.workerActivations}.`,
+							context,
+						);
+						return controller.prompt({ message: `pong: ${message}`, images: null }, context);
+					},
+				}),
+			);
+		});
+	},
+});