@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevSpecAI
+
+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.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# DevSpec for Pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect the [Pi](https://pi.dev) coding agent to [DevSpec](https://devspec.ai) with a single native package. Once installed and signed in, Pi connects to your DevSpec project automatically when you start it in a repository linked to that project, appears on your project's **Agents** page, works from your tasks, decisions, and documents, and can be steered live from your phone or the web.
+
+## Requirements
+
+- [Pi](https://pi.dev) 1.0 or later
+- Node.js 22.19 or later
+
+Full commit tracking — every commit reported to DevSpec and tagged with its task automatically — works on macOS, Linux, and Windows, both natively and through WSL. On native Windows, Pi runs its commands in Git Bash, which comes with [Git for Windows](https://git-scm.com/download/win) and is what Pi uses there by default. If Pi's shell is the older WSL `bash.exe` instead, Pi does not see the agent's commits, so the agent adds the task tag itself and DevSpec links the commits to their tasks later.
+
+## Setup
+
+### 1. Install Pi
+
+On macOS and Linux:
+
+```bash
+curl -fsSL https://pi.dev/install.sh | sh
+```
+
+On Windows PowerShell:
+
+```powershell
+powershell -c "irm https://pi.dev/install.ps1 | iex"
+```
+
+### 2. Install the DevSpec package
+
+Install the DevSpec package at user level (without `-l`) so every folder has DevSpec:
+
+```bash
+pi install npm:@devspecai/pi-plugin
+```
+
+(If npm is unreachable in your environment, you can also install directly from GitHub with `pi install git:github.com/DevSpecAI/DevSpec-Pi`.)
+
+This package provides native DevSpec tools, authentication, project selection, and remote control. No separate DevSpec MCP server entry is needed. (If you previously added DevSpec to Pi's `/mcp` settings, the package disables that duplicate entry so its tools aren't loaded twice.)
+
+**Optional recommended extensions** (delegated subagents and web search):
+
+```bash
+pi install npm:pi-subagents
+pi install npm:pi-exa
+```
+
+### 3. Sign in with your DevSpec token
+
+Create an access token with **Read & write** access on your [Agent setup](https://app.devspec.ai/settings/agents) page, then start `pi` and run:
+
+```text
+/devspec.login dvs_your_token_here
+```
+
+Your token is saved locally (`~/.pi/agent/devspec/auth.json`) with owner-only permissions and works across all of your DevSpec projects.
+
+### 4. Start Pi and connect to your project
+
+- **Inside a linked repository:** Start `pi` in the folder where you cloned the Git repository linked to your DevSpec project. Pi matches the repository to your project automatically and appears on the project's **Agents** page.
+- **In any other folder, or when switching projects:** Start `pi` and run `/devspec.project` to choose which project this conversation belongs to (or launch with `pi --devspec-project "Client Website"`).
+
+## Commands
+
+Everything in DevSpec can be asked in plain words ("Work on DevSpec task 4f2a", "What did we decide about caching?", "Create a task for the login redirect bug"). The package also adds these slash commands in Pi:
+
+| Command | What it does |
+|---|---|
+| `/devspec.login <token>` | Signs Pi in to DevSpec with your `dvs_…` access token. |
+| `/devspec.logout` | Removes the stored token from this computer. |
+| `/devspec.status` | Shows whether you're connected, as whom, and to which project and session. |
+| `/devspec.project` | Opens the project menu to inspect or change the project for this conversation or folder. |
+| `/devspec.remote` | Connects this conversation to DevSpec (or pass `--project`, `--session <id>`, `--new`, `--new --private`, or `--name "…"`). |
+| `/devspec.remote-stop` | Disconnects this Pi conversation from DevSpec while leaving other terminals running. |
+| `/devspec.work` | Lists open tasks or claims a specific task by ID or title to start working on it. |
+| `/devspec.pin <project-uuid>` | Writes `.devspec/project.json` in the current folder to pin it to that project. |
+
+## Choosing and remembering a project
+
+When a repository belongs to more than one DevSpec project, or you start Pi in a folder without a Git remote, Pi prompts you to pick from your accessible projects.
+
+You can also target a project directly:
+
+```text
+pi --devspec-project "Client Website"
+/devspec.remote --project "Client Website"
+/devspec.remote --project <project-id> --session <session-id>
+```
+
+Use `/devspec.project` to manage the current conversation's project and folder default:
+
+- `/devspec.project status` shows the selected project, organization, full project ID, how it was selected, and any folder default.
+- `/devspec.project choose` selects a project for this conversation. Switching away from a project you have already been working in starts a fresh local conversation so context from one project never leaks into another.
+- `/devspec.project remember` saves the current project to `.devspec/project.json` in the folder after showing the file path and asking for confirmation.
+- `/devspec.project forget` removes the `.devspec/project.json` folder default after confirmation without disconnecting active conversations.
+
+## Updating
+
+To update the package to the latest version, run:
+
+```bash
+pi update
+```
+
+Then restart any open `pi` sessions so the updated package is loaded.

package/extensions/core/activation-recovery.ts

@@ -0,0 +1,135 @@
+/**
+ * DevSpec Pi — resume/duplicate recovery for deferred tool activation
+ * (DevSpec item dc8f52d4).
+ *
+ * Per-process activation state and the transcript's permanent addedToolNames
+ * announcements diverge across a resume: session_start rebuilds the hot set,
+ * but every announcement stays in history. Pi's Kimi deferred-tools serializer
+ * (openai-completions, deferredToolsMode "kimi") re-injects a full tool
+ * definition after EVERY toolResult group in history that announced tools, so
+ * a tool announced twice in one transcript reaches the provider wire twice —
+ * the request hard-fails ("duplicate tool names are not allowed") and every
+ * later turn re-renders the same history, bricking the session. Two defences:
+ *
+ *  1. scanTranscriptToolState — on session_start, restore exactly the rare
+ *     tools the current branch already announced (minus recorded recoveries),
+ *     so the loader reports them "already active" instead of re-announcing.
+ *     Fresh sessions have announced nothing, so the happy path is untouched.
+ *     Restoring also keeps Kimi-mode mid-history injections byte-identical
+ *     across a resume instead of silently re-rendering them.
+ *  2. planDuplicateRecovery — if a duplicate-tools provider error still occurs
+ *     (e.g. a transcript poisoned before this fix), the named tools are
+ *     deactivated for the session. Kimi-mode injections resolve against the
+ *     CURRENT tool set, so deactivation clears every copy on the next turn.
+ *
+ * The serializer-side fix (dedupe injected names per request, subtract called
+ * tools) belongs upstream in Pi — see the follow-up item linked from
+ * dc8f52d4. This module is the extension-side compensation.
+ */
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+/** Session-persisted custom entry type recording recovery denials. */
+export const RECOVERY_ENTRY_TYPE = "devspec-tool-recovery";
+
+/** Fireworks/OpenAI-compatible rejection observed in the wild (item dc8f52d4). */
+export const DUPLICATE_TOOL_NAMES_PATTERN =
+	/duplicate tool names are not allowed:\s*\[([^\]]*)\]/i;
+
+/** Parse `['a', 'b']` / `["a"]` name lists out of a provider error message. */
+export function parseDuplicateToolNames(message: string): string[] {
+	const match = DUPLICATE_TOOL_NAMES_PATTERN.exec(message);
+	if (!match) return [];
+	const names: string[] = [];
+	for (const part of match[1].matchAll(/'([^']+)'|"([^"]+)"/g)) {
+		names.push(part[1] ?? part[2]);
+	}
+	return names;
+}
+
+export interface TranscriptToolState {
+	/** Rare tools the branch has announced and not been denied — re-activate these. */
+	restore: string[];
+	/** Tools a previous recovery deactivated in this session. */
+	denied: string[];
+}
+
+/**
+ * Walk one branch of the transcript. Announcements come from toolResult
+ * messages' addedToolNames (stamped by Pi core's tool wrapper); denials come
+ * from custom entries written by the recovery path. Both are filtered through
+ * `isRare` so only loader-managed verbs are ever restored.
+ */
+export function scanTranscriptToolState(
+	entries: readonly SessionEntry[],
+	isRare: (name: string) => boolean,
+): TranscriptToolState {
+	const announced: string[] = [];
+	const announcedSeen = new Set<string>();
+	const denied: string[] = [];
+	const deniedSeen = new Set<string>();
+	for (const entry of entries) {
+		if (entry.type === "message") {
+			const message = entry.message;
+			if (message.role !== "toolResult") continue;
+			// Pre-1.0 transcripts may retain this historical field. Pi 1.x owns
+			// current tool-state messages; do not assume every tool result has it.
+			const legacyNames = (message as typeof message & { addedToolNames?: unknown }).addedToolNames;
+			if (!Array.isArray(legacyNames)) continue;
+			for (const name of legacyNames) {
+				if (typeof name !== "string" || !isRare(name) || announcedSeen.has(name)) continue;
+				announcedSeen.add(name);
+				announced.push(name);
+			}
+		} else if (entry.type === "custom" && entry.customType === RECOVERY_ENTRY_TYPE) {
+			const list = (entry.data as { denied?: unknown } | undefined)?.denied;
+			if (!Array.isArray(list)) continue;
+			for (const name of list) {
+				if (typeof name !== "string" || deniedSeen.has(name)) continue;
+				deniedSeen.add(name);
+				denied.push(name);
+			}
+		}
+	}
+	return { restore: announced.filter((name) => !deniedSeen.has(name)), denied };
+}
+
+/** Append previously announced tools missing from the active set; order-stable. */
+export function withRestoredTools(active: readonly string[], restore: readonly string[]): string[] {
+	if (restore.length === 0) return [...active];
+	const seen = new Set(active);
+	return [...active, ...restore.filter((name) => !seen.has(name))];
+}
+
+export interface DuplicateRecoveryPlan {
+	names: string[];
+	errorMessage: string;
+}
+
+/**
+ * Decide which tools to deactivate after a duplicate-tools provider error.
+ * Only catalog tools that are currently active and not already denied are
+ * actionable; a re-fired error whose names are all handled returns null so
+ * the recovery path can never loop.
+ */
+export function planDuplicateRecovery(
+	messages: readonly unknown[],
+	opts: {
+		isCatalogTool: (name: string) => boolean;
+		isActive: (name: string) => boolean;
+		isDenied: (name: string) => boolean;
+	},
+): DuplicateRecoveryPlan | null {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const errorMessage = (messages[index] as { errorMessage?: unknown } | null | undefined)
+			?.errorMessage;
+		if (typeof errorMessage !== "string" || !DUPLICATE_TOOL_NAMES_PATTERN.test(errorMessage)) {
+			continue;
+		}
+		const names = parseDuplicateToolNames(errorMessage).filter(
+			(name) => opts.isCatalogTool(name) && opts.isActive(name) && !opts.isDenied(name),
+		);
+		return names.length > 0 ? { names, errorMessage } : null;
+	}
+	return null;
+}

package/extensions/core/active-deliveries.ts

@@ -0,0 +1,171 @@
+import type { ImplementationContractContext, ImplementationKickoff } from "./implementation-contract.ts";
+
+/**
+ * Which deliveries this Pi process has handed to a turn and not yet seen finish.
+ *
+ * This was `implementation-mode.ts`, and it installed an execution mode for the
+ * duration of a delivery. There is no execution mode (DevSpec item 6d085535):
+ * nothing is installed for the duration of a batch and nothing needs clearing when
+ * one resolves. What is genuinely worth tracking is narrower and survives the
+ * rename — WHICH locally selected items went out with WHICH contract, so the footer
+ * can say so and a failed direct send can be rolled back.
+ *
+ * Plural direct deliveries coexist on purpose, so a lifecycle result only ever
+ * touches the delivery holding that item.
+ */
+
+export interface ActiveDelivery {
+	deliveryKey: string;
+	taskIds: string[];
+	terminalTaskIds: string[];
+	contractVersion: string;
+	contractHash?: string;
+	recordedAt: number;
+	generation: number;
+}
+
+export interface DeliveryRecord {
+	deliveryKey: string;
+	generation: number;
+	previous?: ActiveDelivery;
+	previousIndex: number;
+}
+
+interface MutableDeliveryState {
+	deliveries: ActiveDelivery[];
+	nextGeneration: number;
+}
+
+const DELIVERIES_KEY = Symbol.for("devspec.pi.active-deliveries.v2");
+
+function state(): MutableDeliveryState {
+	const root = globalThis as typeof globalThis & { [DELIVERIES_KEY]?: MutableDeliveryState };
+	if (!root[DELIVERIES_KEY]) root[DELIVERIES_KEY] = { deliveries: [], nextGeneration: 1 };
+	if (!Number.isFinite(root[DELIVERIES_KEY].nextGeneration)) root[DELIVERIES_KEY].nextGeneration = 1;
+	return root[DELIVERIES_KEY];
+}
+
+function unique(values: readonly string[]): string[] {
+	return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
+function kickoffKey(kickoff: ImplementationKickoff): string {
+	return `items:${[...kickoff.work.task_ids].sort().join(",")}`;
+}
+
+function copy(active: ActiveDelivery): ActiveDelivery {
+	return {
+		...active,
+		taskIds: [...active.taskIds],
+		terminalTaskIds: [...active.terminalTaskIds],
+	};
+}
+
+/** Record exactly one locally selected delivery; a delivery is not connection identity. */
+export function recordActiveDelivery(
+	kickoff: ImplementationKickoff,
+	context: ImplementationContractContext,
+): DeliveryRecord {
+	const current = state();
+	const deliveryKey = kickoffKey(kickoff);
+	const previousIndex = current.deliveries.findIndex((entry) => entry.deliveryKey === deliveryKey);
+	const previous = previousIndex >= 0 ? copy(current.deliveries[previousIndex]!) : undefined;
+	const generation = current.nextGeneration++;
+	const taskIds = unique(kickoff.work.task_ids);
+	const next: ActiveDelivery = {
+		deliveryKey,
+		taskIds,
+		terminalTaskIds: previous?.terminalTaskIds.filter((id) => taskIds.includes(id)) ?? [],
+		contractVersion: context.contractVersion,
+		...(context.contractHash ? { contractHash: context.contractHash } : {}),
+		recordedAt: Date.now(),
+		generation,
+	};
+	current.deliveries = [
+		...current.deliveries.filter((entry) => entry.deliveryKey !== deliveryKey),
+		next,
+	];
+	return {
+		deliveryKey,
+		generation,
+		...(previous ? { previous } : {}),
+		previousIndex,
+	};
+}
+
+/** Most recently recorded delivery, retained for footer/debug compatibility. */
+export function getLatestActiveDelivery(): ActiveDelivery | null {
+	const deliveries = state().deliveries;
+	return deliveries.length > 0 ? copy(deliveries[deliveries.length - 1]!) : null;
+}
+
+export function listActiveDeliveries(): ActiveDelivery[] {
+	return state().deliveries.map(copy);
+}
+
+export function clearActiveDelivery(input: { deliveryKey: string }): boolean {
+	const current = state();
+	if (!input.deliveryKey) return false;
+	const before = current.deliveries.length;
+	current.deliveries = current.deliveries.filter((entry) => entry.deliveryKey !== input.deliveryKey);
+	return current.deliveries.length !== before;
+}
+
+export function rollbackActiveDelivery(record: DeliveryRecord): boolean {
+	const current = state();
+	const activeIndex = current.deliveries.findIndex((entry) =>
+		entry.deliveryKey === record.deliveryKey && entry.generation === record.generation
+	);
+	if (activeIndex < 0) return false;
+	current.deliveries.splice(activeIndex, 1);
+	if (record.previous) {
+		const index = Math.max(0, Math.min(record.previousIndex, current.deliveries.length));
+		current.deliveries.splice(index, 0, copy(record.previous));
+	}
+	return true;
+}
+
+function itemIdFrom(value: unknown): string | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const root = value as Record<string, unknown>;
+	for (const key of ["task_id", "id"]) {
+		if (typeof root[key] === "string" && root[key]) return root[key] as string;
+	}
+	for (const key of ["item", "task", "details"]) {
+		const nested = itemIdFrom(root[key]);
+		if (nested) return nested;
+	}
+	return undefined;
+}
+
+/**
+ * Successful native work-tool results drive the matching delivery's cleanup.
+ * Plural local selections coexist; no unrelated delivery can be cleared.
+ */
+export function consumeDeliveryLifecycle(
+	name: string,
+	args: Record<string, unknown> = {},
+	result?: unknown,
+): boolean {
+	const current = state();
+	if (current.deliveries.length === 0) return false;
+
+	if (!["record_implementation", "release_work_item", "fail_work_item"].includes(name)) return false;
+	const taskId =
+		(typeof args.task_id === "string" && args.task_id ? args.task_id : undefined) ??
+		itemIdFrom(result);
+	if (!taskId) return false;
+	const delivery = current.deliveries.find((entry) => entry.taskIds.includes(taskId));
+	if (!delivery) return false;
+	delivery.terminalTaskIds = unique([...delivery.terminalTaskIds, taskId]);
+	if (delivery.taskIds.every((id) => delivery.terminalTaskIds.includes(id))) {
+		return clearActiveDelivery({ deliveryKey: delivery.deliveryKey });
+	}
+	return false;
+}
+
+export function resetActiveDeliveries(): void {
+	const current = state();
+	current.deliveries = [];
+	current.nextGeneration = 1;
+}