pi-soly 0.2.1

package/nudge.ts

@@ -0,0 +1,123 @@
+// =============================================================================
+// nudge.ts — Behavioral nudge for the soly extension
+// =============================================================================
+//
+// Goal: gently push the agent toward "ask before acting on non-trivial
+// tasks" and "use background subagents with fresh context for research".
+//
+// Implementation is prompt-only (no UI blocking) — the model reads the nudge
+// in its system prompt and follows it. Heuristics on the user prompt tell the
+// model WHY this prompt triggers the nudge, so it can decide whether to ask
+// one short clarifying question or just go.
+//
+// The input event also surfaces a soft UI notify to the human, so they know
+// the model was told to pause and ask — but it never blocks input.
+// =============================================================================
+
+// Words that suggest the user is asking for non-trivial changes.
+const NON_TRIVIAL_VERBS =
+	/\b(add|create|build|implement|refactor|migrate|rewrite|redesign|port|convert|integrate|introduce|extract|split|merge|restructure|optimize|generate|scaffold|set up|wire up)\b/i;
+
+// Words that suggest the user is asking the model to go look something up.
+const RESEARCH_VERBS =
+	/\b(find out|look up|check|verify|investigate|research|figure out|figure out how|discover|why does|how does|what is the best|compare|which library|which approach|benchmark|audit|review|trace|debug why)\b/i;
+
+const URL_PATTERN = /https?:\/\/\S+/;
+// Library/version-ish reference (e.g. v1.2.3, @scope/pkg).
+// NB: no leading `\b` — `@` is a non-word char so `\b` won't match before it.
+// We use a negative lookbehind on word chars instead.
+const VERSION_PATTERN = /(?<!\w)(v?\d+\.\d+(?:\.\d+)?|@[\w\-]+\/[\w\-]+)(?!\w)/;
+
+export interface TaskHeuristics {
+	nonTrivial: boolean;
+	researchHeavy: boolean;
+	mentions: string[];
+	suggestedAngles: string[];
+}
+
+export function classifyTaskHeuristics(prompt: string): TaskHeuristics {
+	const trimmed = prompt.trim();
+	const long = trimmed.length > 80;
+	const hasVerb = NON_TRIVIAL_VERBS.test(trimmed);
+	const hasResearch = RESEARCH_VERBS.test(trimmed);
+	const hasUrl = URL_PATTERN.test(trimmed);
+	const hasVersion = VERSION_PATTERN.test(trimmed);
+
+	// Extract file-ish mentions from the prompt. We don't import core's
+	// extractFilePathsFromPrompt to keep nudge.ts self-contained.
+	const fileLike =
+		trimmed.match(/(?:\.{0,2}\/)?(?:[A-Za-z0-9_\-]+\/)+[A-Za-z0-9_\-.]+\.[A-Za-z0-9]{1,5}/g) ||
+		trimmed.match(/[A-Za-z0-9_\-.]+\.[a-z]{1,5}/g) ||
+		[];
+	const mentions: string[] = [];
+	if (fileLike.length >= 2) mentions.push(`${fileLike.length} file references`);
+	if (hasUrl) mentions.push("external URL");
+	if (hasVersion) mentions.push("version/library ref");
+
+	// nonTrivial = enough complexity that assumptions matter
+	const nonTrivial =
+		long || hasVerb || fileLike.length >= 2 || mentions.length > 0;
+
+	// researchHeavy = model can't answer from rules/code alone
+	const researchHeavy = hasResearch || hasUrl || hasVersion;
+
+	// Suggested clarification angles — only what the heuristic actually
+	// detected, no over-eager prompting.
+	const suggestedAngles: string[] = [];
+	if (fileLike.length >= 2) {
+		suggestedAngles.push("which files are in scope vs out of scope?");
+	}
+	if (hasVerb && !hasUrl && !hasVersion) {
+		suggestedAngles.push("what does \"done\" look like for this task?");
+	}
+	if (researchHeavy) {
+		suggestedAngles.push(
+			"is there a specific source/result you trust, or should I dig?",
+		);
+	}
+	if (mentions.length === 0 && nonTrivial) {
+		suggestedAngles.push("any constraints (deadline, scope, style) I should know?");
+	}
+
+	return { nonTrivial, researchHeavy, mentions, suggestedAngles };
+}
+
+export function buildNudgeSection(heuristics: TaskHeuristics): string {
+	// Always-on rules (cheap to add, high signal):
+	//   - Don't dive in on non-trivial tasks without a brief check
+	//   - Prefer background subagents for research
+	// Conditional guidance based on what the prompt actually looks like.
+	const triggers: string[] = [];
+	if (heuristics.nonTrivial) {
+		triggers.push("non-trivial task (long prompt / action verb / multiple files)");
+	}
+	if (heuristics.researchHeavy) {
+		triggers.push("research-heavy (web lookup / library decision / unknown behavior)");
+	}
+
+	const triggerLine = triggers.length
+		? `Heuristics for this prompt: ${triggers.join("; ")}.`
+		: "Heuristics for this prompt: looks routine.";
+
+	const anglesBlock = heuristics.suggestedAngles.length
+		? `\n\nPossible clarifying questions (pick at most 1–2 that actually unblock you, or skip if you can answer from the prompt):\n${heuristics.suggestedAngles
+				.map((a, i) => `  ${i + 1}. ${a}`)
+				.join("\n")}`
+		: "";
+
+	return `
+
+## soly behavioral nudge (always on)
+
+The following are user-set defaults, not project rules. They tell you how the user wants you to behave in this session.
+
+1. **Pre-action gate.** Before starting non-trivial work, take a 10-second pause and decide: do I have enough to act, or should I ask? If the prompt has ambiguity, missing scope, or a hidden assumption, surface one short clarifying question (or a small set of multi-choice options) instead of starting to code. Skip the gate for trivial fixes ("rename X", "add log line", "fix typo") and for follow-up turns in an already-clarified task.
+   ${triggerLine}${anglesBlock}
+
+2. **Background subagents by default.** When you need to read unfamiliar code, scout a directory, gather external evidence, or run a multi-step review, prefer \`subagent(...)\` with \`async: true\` and \`context: "fresh"\` over doing it inline. Reserve your own context for the actual decision the user is paying you to make. If the work needs the parent conversation history, use \`context: "fork"\` instead. Do not silently block on long runs — launch async and continue with independent work.
+
+3. **Subagent tool ergonomics.** When delegating: give the child a concrete role, scope, success criteria, hard constraints, and expected output. Do not pass vague instructions like "implement this" or "look into that". Async is the default; foreground is the explicit opt-out.
+
+Treat (1) and (2) as defaults, not laws. The user can always override per-task ("just do it", "ask me everything", "no subagents"). When overriding, briefly acknowledge it.
+`;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "pi-soly",
+  "version": "0.2.1",
+  "description": "Project management for pi — plans, state, subagent-driven execution. Inspired by GSD.",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.78.1",
+    "@earendil-works/pi-coding-agent": "0.78.1",
+    "@types/node": "^25.9.1",
+    "bun-types": "^1.3.14",
+    "typebox": "1.1.38",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "commands.ts",
+    "config.ts",
+    "core.ts",
+    "docs.ts",
+    "env.ts",
+    "git.ts",
+    "html.ts",
+    "index.ts",
+    "integrations.ts",
+    "intent.ts",
+    "iteration.ts",
+    "nudge.ts",
+    "scratchpad.ts",
+    "tools.ts",
+    "agents-install.ts",
+    "agents",
+    "workflows",
+    "workflows-data"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "project-management",
+    "planning",
+    "subagents"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "http://git.local.stbl/lowern1ght/pi-soly.framework.git",
+    "directory": "packages/soly"
+  }
+}

package/scratchpad.ts

@@ -0,0 +1,117 @@
+// =============================================================================
+// scratchpad.ts — Working memory tool support
+// =============================================================================
+//
+// Reads the recent conversation history (filtered to current branch) and
+// produces a compact "scratchpad" summary: each turn's user prompt + first
+// line of the assistant response. Used by soly_scratchpad tool to give the
+// model (or a sibling context) cheap access to "what we just discussed".
+//
+// Pure: this module has no I/O and no state. It operates on the session
+// branch that the LLM tool handler passes in.
+// =============================================================================
+
+const SCRATCHPAD_MAX_TURNS = 50;
+
+export interface ScratchpadEntry {
+	turn: number;
+	role: "user" | "assistant" | "tool";
+	summary: string;
+	/** Tokens estimated for this entry. */
+	tokens: number;
+}
+
+export interface Scratchpad {
+	branchLength: number;
+	turnCount: number;
+	entries: ScratchpadEntry[];
+	fromTurn: number;
+}
+
+/** Extract a short, useful summary from a message's text content. */
+function summarizeMessage(role: string, text: string, maxLen = 200): string {
+	if (!text) return "";
+	const trimmed = text.trim();
+	if (!trimmed) return "";
+	if (role === "tool") {
+		// Tool results: just first non-empty line
+		const first = trimmed.split(/\r?\n/).find((l) => l.trim());
+		return (first ?? "").slice(0, maxLen);
+	}
+	// For user/assistant: take the first paragraph or first maxLen chars
+	const firstPara = trimmed.split(/\r?\n\s*\r?\n/)[0] ?? trimmed;
+	return firstPara.length > maxLen
+		? firstPara.slice(0, maxLen) + "…"
+		: firstPara;
+}
+
+/** Extract plain text from a message's content array. */
+function messageText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		const parts: string[] = [];
+		for (const block of content) {
+			if (
+				block &&
+				typeof block === "object" &&
+				"type" in block &&
+				(block as { type: string }).type === "text" &&
+				"text" in block &&
+				typeof (block as { text: unknown }).text === "string"
+			) {
+				parts.push((block as { text: string }).text);
+			}
+		}
+		return parts.join("\n");
+	}
+	return "";
+}
+
+/** Build a scratchpad of recent conversation turns. */
+export function buildScratchpad(
+	entries: readonly { type: string; message?: { role?: string; content?: unknown } }[],
+	limit = 20,
+): Scratchpad {
+	// Walk backwards, collect messages, stop at limit turns (user prompts)
+	const collected: ScratchpadEntry[] = [];
+	let userTurnCount = 0;
+	const startIdx = entries.length;
+
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const e = entries[i];
+		if (e.type !== "message" || !e.message) continue;
+		const role = e.message.role ?? "user";
+		const text = messageText(e.message.content);
+		const summary = summarizeMessage(role, text);
+		if (!summary) continue;
+		collected.unshift({
+			turn: startIdx - i,
+			role: role as ScratchpadEntry["role"],
+			summary,
+			tokens: Math.ceil(summary.length / 4),
+		});
+		if (role === "user") {
+			userTurnCount++;
+			if (userTurnCount >= limit) {
+				return {
+					branchLength: entries.length,
+					turnCount: userTurnCount,
+					entries: collected,
+					fromTurn: startIdx - i,
+				};
+			}
+		}
+	}
+
+	return {
+		branchLength: entries.length,
+		turnCount: userTurnCount,
+		entries: collected,
+		fromTurn: 1,
+	};
+}
+
+export const SCRATCHPAD_LIMITS = {
+	default: 20,
+	max: SCRATCHPAD_MAX_TURNS,
+} as const;