pi-improve-interation 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ai-feier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,57 @@
+# pi-improve-interation
+
+English | [中文](./README.md)
+
+## Summary
+
+A companion pi package that layers enhancements on top of interactions you already use — pi-native and upstream pi plugins alike. One idea only: keep the interactions you know, make them stronger.
+
+- No fork of upstream: public extension APIs only, so an upstream upgrade costs at most one adapter change
+- No parallel concepts: it enhances the `@` you already type and the work you already delegate
+
+## What It Enhances
+
+The current target is [pi-subagents](https://github.com/badlogic/pi-subagents) (the sub-agent orchestration package):
+
+| Scenario | Before | After |
+| --- | --- | --- |
+| Typing `@` in the composer | File completion only | Also completes agents (`@rev` → `@agent:reviewer`; built-ins + your custom agents) |
+| Delegating to a sub-agent | Assembling subagent-call prompts by hand | Write `@agent:<name> <task>`; the extension turns it into an explicit delegation instruction |
+| Unsure the layer is wired up | Digging through config and logs | `/plus-doctor` pinpoints it in one command |
+
+## Install
+
+```bash
+pi install npm:pi-subagents             # prerequisite
+pi install npm:pi-improve-interation
+```
+
+Restart pi and run `/plus-doctor`. Seeing `OK  pi-subagents (pi-subagents): delegation event transport resolved …` means the wiring is good.
+
+For local development: `pi install /path/to/pi-improve-interation`
+
+## Contributing
+
+The package is organized around adapters: each enhanced upstream package gets one `PluginAdapter` (probe returns diagnostics, never throws), and enhancements stay host-agnostic.
+
+```text
+extensions/plus.ts          pi extension entry: /plus-doctor, @ panel, input transform
+src/adapters/types.ts       PluginAdapter contract (single source of truth)
+src/adapters/index.ts       adapter registry
+src/adapters/pi-subagents/  the only adapter today
+```
+
+To enhance another plugin:
+
+1. Implement `src/adapters/<pkg>/`; the contract lives in `src/adapters/types.ts` (probe never throws, returns diagnostics only)
+2. Register it in `src/adapters/index.ts` and add a registry assertion to `test/wiring.test.ts`
+3. `npm run typecheck && npm test`
+
+Roadmap (contributions welcome):
+
+- [ ] Delegation event transport orchestration enhancements (visible progress, retries, budget control)
+- [ ] A second adapter
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,57 @@
+# pi-improve-interation
+
+[English](./README.en.md) | 中文
+
+## Summary
+
+给 pi 原生与上游 pi 插件**已有交互**叠加增强的伴生包。核心只有一件事：让你继续用熟悉的交互，但更强。
+
+- 不 fork 上游：只走宿主公开扩展 API，上游升级最多改一处 adapter
+- 不引入平行概念：增强的就是你已经在敲的 `@`、已经在派的活
+
+## 增强了什么
+
+当前增强对象是 [pi-subagents](https://github.com/badlogic/pi-subagents)（子 agent 编排包）：
+
+| 场景 | 之前 | 之后 |
+| --- | --- | --- |
+| 输入框敲 `@` | 只有文件补全 | 同时补全 agent（`@rev` → `@agent:reviewer`，含内置 + 你的自定义 agents） |
+| 派活给子 agent | 自己拼 subagent 调用话术 | 直接写 `@agent:<name> <任务>`，扩展自动转成显式委派指令 |
+| 怀疑增强层没接上 | 翻配置、看日志 | `/plus-doctor` 一条命令定位 |
+
+## 如何安装
+
+```bash
+pi install npm:pi-subagents             # 前置
+pi install npm:pi-improve-interation
+```
+
+重启 pi，敲 `/plus-doctor`。看到 `OK  pi-subagents (pi-subagents): delegation event transport resolved …` 即接线成功。
+
+本地开发装法：`pi install /path/to/pi-improve-interation`
+
+## 贡献
+
+本包按 adapter 组织：每个被增强的上游包对应一个 `PluginAdapter`（probe 只返回诊断、永不抛错），增强功能宿主无关。
+
+```text
+extensions/plus.ts          pi 扩展入口：/plus-doctor、@ 面板、input 转换
+src/adapters/types.ts       PluginAdapter 契约（唯一来源）
+src/adapters/index.ts       adapter 注册表
+src/adapters/pi-subagents/  当前唯一 adapter
+```
+
+给下一个插件加增强：
+
+1. 实现 `src/adapters/<pkg>/`，契约见 `src/adapters/types.ts`（probe 永不抛错，只返回诊断）
+2. 追加进 `src/adapters/index.ts`，在 `test/wiring.test.ts` 补一条注册表断言
+3. `npm run typecheck && npm test`
+
+Roadmap（欢迎认领）：
+
+- [ ] delegation event transport 编排增强（进度可见、重试、预算控制）
+- [ ] 第二个 adapter
+
+## License
+
+[MIT](./LICENSE)

package/extensions/plus.ts

@@ -0,0 +1,93 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runDoctor, type DoctorLine } from "../src/commands/doctor.ts";
+import {
+	buildDelegationInstruction,
+	AGENT_MENTION_TOKEN_PATTERN,
+} from "../src/commands/delegation.ts";
+import {
+	listBuiltinAgents,
+	listCustomAgents,
+	mergeAgentEntries,
+	type AgentEntry,
+} from "../src/adapters/pi-subagents/agents.ts";
+import { createAgentAutocompleteProvider } from "../src/adapters/pi-subagents/autocomplete.ts";
+
+/**
+ * pi-subagents runtime agent registration event (pi-subagents:runtime-agent-register:v1).
+ * Literal on purpose: importing "pi-subagents/agents" at load time would crash this
+ * extension when the host package is absent; the adapter probe validates the real
+ * exported constant instead.
+ */
+const RUNTIME_AGENT_REGISTER_EVENT = "pi-subagents:runtime-agent-register:v1";
+
+async function discoverAgents(
+	runtimeAgentNames: ReadonlySet<string>,
+): Promise<AgentEntry[]> {
+	const [builtins, customs] = await Promise.all([
+		listBuiltinAgents(),
+		listCustomAgents(process.cwd()),
+	]);
+	const runtime: AgentEntry[] = [...runtimeAgentNames].map((name) => ({
+		name,
+		source: "runtime",
+	}));
+	return mergeAgentEntries(builtins, customs, runtime);
+}
+
+/**
+ * pi-improve-interation — companion extension entry.
+ *
+ * Loads alongside pi-subagents (installed as its own pi package) and adds
+ * orchestration enhancements through pi-subagents' public API surface.
+ *
+ * Agent entry point (only): typing "@" in the composer autocompletes agents;
+ * a sent message containing "@agent:<name>" is transformed, before agent
+ * processing, into an explicit delegation instruction for the main session.
+ */
+export default function registerPlusExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("plus-doctor", {
+		description:
+			"Diagnose pi-improve-interation wiring: adapter registry and host package availability",
+		handler: async (_args, ctx) => {
+			const lines: DoctorLine[] = await runDoctor();
+			const allOk = lines.every((line) => line.level !== "fail");
+			ctx.ui.notify(
+				lines.map((line) => line.text).join("\n"),
+				allOk ? "info" : "error",
+			);
+		},
+	});
+
+	const runtimeAgentNames = new Set<string>();
+	let cachedAgents: Promise<AgentEntry[]> | null = null;
+	const getAgents = (): Promise<AgentEntry[]> =>
+		(cachedAgents ??= discoverAgents(runtimeAgentNames));
+
+	pi.events.on(RUNTIME_AGENT_REGISTER_EVENT, (payload: unknown) => {
+		const name = (payload as { name?: unknown } | null | undefined)?.name;
+		if (typeof name === "string" && name.length > 0) {
+			runtimeAgentNames.add(name);
+			cachedAgents = null;
+		}
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.addAutocompleteProvider((current) =>
+			createAgentAutocompleteProvider(current, getAgents),
+		);
+	});
+
+	// Transform "@agent:<name> …" messages into explicit delegation
+	// instructions before the main agent sees them (pi "input" event).
+	pi.on("input", (event) => {
+		const match = AGENT_MENTION_TOKEN_PATTERN.exec(event.text);
+		if (!match?.[1]) {
+			return { action: "continue" };
+		}
+		const task = event.text.replace(match[0], " ").replace(/\s+/g, " ").trim();
+		return {
+			action: "transform",
+			text: buildDelegationInstruction(match[1], task),
+		};
+	});
+}