ultimate-pi 0.19.0 → 0.19.1

package/.pi/harness/web-heuristic-angles.yaml

@@ -0,0 +1,182 @@
+# WRS emergency heuristic angles (--expand-heuristic / expandHeuristic:true).
+# Package defaults (ultimate-pi). External projects: copy
+# .pi/harness/examples/web-heuristic-angles.project.yaml to
+# <your-project>/.pi/harness/web-heuristic-angles.yaml and edit.
+#
+# Placeholders: {query} → user search string
+# Order matters: base angles run first, then category (deduped by id, capped at max_angles).
+# JSON mirror (no PyYAML): run `node .pi/scripts/gen-web-heuristic-angles-json.mjs` after edits.
+# Stdlib fallback: .pi/scripts/harness_web/heuristic_angles_shipped.py
+
+version: 1
+max_angles: 8
+
+base:
+  - id: definitional
+    query: "{query}"
+    rationale: Core intent phrasing
+  - id: authoritative
+    query: "{query} official documentation OR specification OR RFC"
+    rationale: Primary specs and vendor docs
+
+categories:
+  code:
+    - id: github
+      query: "{query} site:github.com"
+      rationale: Source, issues, discussions
+    - id: stackoverflow
+      query: "{query} site:stackoverflow.com"
+      rationale: Debugging and API usage Q&A
+    - id: stackexchange
+      query: "{query} site:stackexchange.com"
+      rationale: Broader SE network (Super User, Server Fault, etc.)
+    - id: readthedocs
+      query: "{query} site:readthedocs.io"
+      rationale: OSS library documentation
+    - id: mdn
+      query: "{query} site:developer.mozilla.org"
+      rationale: Web platform and browser APIs
+    - id: package_registries
+      query: "{query} site:npmjs.com OR site:pypi.org OR site:pkg.go.dev OR site:crates.io"
+      rationale: Package metadata across major ecosystems
+    - id: microsoft_learn
+      query: "{query} site:learn.microsoft.com"
+      rationale: .NET, Azure, Windows, and enterprise stacks
+    - id: hacker_news
+      query: "{query} site:news.ycombinator.com"
+      rationale: High-signal practitioner discussion
+    - id: gitlab
+      query: "{query} site:gitlab.com"
+      rationale: Alternate host and CI-visible code
+    - id: devto
+      query: "{query} site:dev.to OR site:medium.com"
+      rationale: Tutorials and implementation writeups
+
+  paper:
+    - id: arxiv
+      query: "{query} site:arxiv.org"
+      rationale: Preprints and latest ML/CS uploads
+    - id: semantic_scholar
+      query: "{query} site:semanticscholar.org"
+      rationale: Citations, influences, and PDF links
+    - id: google_scholar
+      query: "{query} site:scholar.google.com"
+      rationale: Broad academic discovery
+    - id: papers_with_code
+      query: "{query} site:paperswithcode.com"
+      rationale: Benchmarks tied to implementations
+    - id: openreview
+      query: "{query} site:openreview.net"
+      rationale: Peer reviews and ML conference submissions
+    - id: acl_anthology
+      query: "{query} site:aclanthology.org"
+      rationale: NLP and computational linguistics
+    - id: acm_dl
+      query: "{query} site:dl.acm.org"
+      rationale: ACM proceedings and journals
+    - id: pubmed
+      query: "{query} site:pubmed.ncbi.nlm.nih.gov"
+      rationale: Biomedical and life-sciences literature
+
+  news:
+    - id: recent
+      query: "{query} news 2025 2026"
+      rationale: Recency-biased open web
+    - id: wire_reuters
+      query: "{query} site:reuters.com"
+      rationale: Wire-service reporting
+    - id: wire_ap
+      query: "{query} site:apnews.com"
+      rationale: Associated Press coverage
+    - id: tech_press
+      query: "{query} site:techcrunch.com OR site:theverge.com OR site:arstechnica.com"
+      rationale: Technology industry news
+    - id: business_press
+      query: "{query} site:bloomberg.com OR site:ft.com OR site:wsj.com"
+      rationale: Markets and business context
+    - id: analysis
+      query: "{query} in-depth analysis explainer"
+      rationale: Long-form journalism and explainers
+    - id: bbc
+      query: "{query} site:bbc.com/news"
+      rationale: International general news desk
+
+  company:
+    - id: official_site
+      query: "{query} official website"
+      rationale: Company-controlled messaging
+    - id: crunchbase
+      query: "{query} site:crunchbase.com"
+      rationale: Funding, investors, and competitors
+    - id: linkedin_company
+      query: "{query} site:linkedin.com/company"
+      rationale: Headcount, hiring, and positioning
+    - id: sec_filings
+      query: "{query} site:sec.gov 10-K OR 10-Q OR S-1"
+      rationale: US public-company disclosures
+    - id: g2_reviews
+      query: "{query} site:g2.com OR site:capterra.com"
+      rationale: B2B software reviews and comparisons
+    - id: company_news
+      query: "{query} company announcement press release"
+      rationale: Launches, partnerships, and earnings
+    - id: glassdoor
+      query: "{query} site:glassdoor.com"
+      rationale: Employee sentiment and culture signals
+
+  people:
+    - id: linkedin
+      query: "{query} site:linkedin.com/in"
+      rationale: Professional profiles
+    - id: github_person
+      query: "{query} site:github.com"
+      rationale: Open-source footprint for builders
+    - id: wikipedia
+      query: "{query} site:en.wikipedia.org"
+      rationale: Neutral biographical baseline
+    - id: scholar_person
+      query: "{query} site:scholar.google.com"
+      rationale: Publication record for researchers
+    - id: interviews
+      query: "{query} interview podcast keynote"
+      rationale: First-person statements and talks
+    - id: twitter_x
+      query: "{query} site:x.com OR site:twitter.com"
+      rationale: Public statements and discourse
+
+  security:
+    - id: cve_nvd
+      query: "{query} CVE site:nvd.nist.gov"
+      rationale: National Vulnerability Database
+    - id: owasp
+      query: "{query} site:owasp.org"
+      rationale: AppSec standards and cheat sheets
+    - id: cwe
+      query: "{query} site:cwe.mitre.org"
+      rationale: Weakness taxonomy
+    - id: github_advisories
+      query: "{query} site:github.com/advisories OR dependabot"
+      rationale: Ecosystem security advisories
+    - id: snyk_blog
+      query: "{query} site:snyk.io/blog OR vulnerability"
+      rationale: Practitioner security writeups
+
+  default:
+    - id: technical
+      query: "{query} how it works architecture internals"
+      rationale: Mechanism and design
+    - id: criticism
+      query: "{query} limitations criticism drawbacks"
+      rationale: Counterpoints and failure modes
+    - id: wikipedia
+      query: "{query} site:en.wikipedia.org"
+      rationale: Structured overview
+    - id: comparison
+      query: "{query} vs alternatives comparison benchmark"
+      rationale: Competitive landscape
+    - id: reddit
+      query: "{query} site:reddit.com"
+      rationale: Community experience reports
+    - id: hn_default
+      query: "{query} site:news.ycombinator.com"
+      rationale: Practitioner threads when category unknown

package/.pi/lib/agents-policy.mjs

@@ -67,6 +67,8 @@ function normalizeKindEntry(raw) {
 			typeof raw.thinking === "string" && raw.thinking.trim()
 				? raw.thinking.trim()
 				: undefined,
+		model:
+			typeof raw.model === "string" && raw.model.trim() ? raw.model.trim() : undefined,
 	};
 }
 
@@ -99,6 +101,8 @@ function normalizeAgentEntry(raw) {
 			typeof raw.thinking === "string" && raw.thinking.trim()
 				? raw.thinking.trim()
 				: undefined,
+		model:
+			typeof raw.model === "string" && raw.model.trim() ? raw.model.trim() : undefined,
 	};
 }
 
@@ -165,6 +169,7 @@ export function resolveEffectiveTools(agentId, merged) {
 		readOnly: kind.readOnly,
 		maxTurns: entry.maxTurns ?? kind.maxTurns,
 		thinking: entry.thinking ?? kind.thinking,
+		model: entry.model ?? kind.model,
 		submitTool: entry.submitTool,
 	};
 }
@@ -301,6 +306,7 @@ export function applyAgentPolicyToConfig(agent, packageRoot, projectRoot) {
 		extensionsOff: spec.extensionsOff,
 		maxTurns: spec.maxTurns ?? agent.maxTurns,
 		thinking: spec.thinking ?? agent.thinking,
+		model: spec.model ?? agent.model,
 	};
 }
 

package/.pi/lib/harness-subagent-auth.ts

@@ -2,7 +2,7 @@
  * Resolve concrete LLM credentials for harness subagent subprocesses.
  *
  * Harness subprocesses run with `--no-extensions`, so auth forwarding only uses
- * concrete provider/model references from the parent session or agent config.
+ * concrete provider/model references from env, agent config, or parent session.
  */
 
 import type { AgentConfig } from "../../vendor/pi-subagents/src/agents.js";
@@ -30,22 +30,52 @@ export interface ConcreteSubagentModel {
 	modelId: string;
 }
 
+function toConcrete(ref: string): ConcreteSubagentModel | undefined {
+	const parsed = parseModelRef(ref);
+	if (!parsed) return undefined;
+	return { modelRef: ref, ...parsed };
+}
+
+const WEB_FAST_AGENT_IDS = new Set([
+	"harness/web-retrieval/web-query-expander-fast",
+	"harness/web-retrieval/web-summarizer",
+	"harness/web-retrieval/web-gap-analyzer",
+]);
+
+const WEB_QUALITY_AGENT_IDS = new Set([
+	"harness/web-retrieval/web-answerer",
+	"harness/web-retrieval/web-criteria-verifier",
+]);
+
+function envModelRef(varName: string): string | undefined {
+	const v = process.env[varName]?.trim();
+	return v && parseModelRef(v) ? v : undefined;
+}
+
+function modelFromEnv(agentName: string): ConcreteSubagentModel | undefined {
+	const fast = envModelRef("HARNESS_WEB_FAST_MODEL");
+	if (fast && WEB_FAST_AGENT_IDS.has(agentName)) return toConcrete(fast);
+	const expander = envModelRef("HARNESS_WEB_EXPANDER_MODEL");
+	if (expander && agentName === "harness/web-retrieval/web-query-expander") return toConcrete(expander);
+	const quality = envModelRef("HARNESS_WEB_QUALITY_MODEL");
+	if (quality && WEB_QUALITY_AGENT_IDS.has(agentName)) return toConcrete(quality);
+	return undefined;
+}
+
 export function resolveConcreteSubagentModel(
 	_parentCwd: string,
 	parentModel: { provider: string; id: string } | undefined,
 	agent: AgentConfig,
 	_taskSnippet?: string,
 ): ConcreteSubagentModel | undefined {
+	const envOverride = modelFromEnv(agent.name);
+	if (envOverride) return envOverride;
+
 	if (agent.model) {
-		const parsed = parseModelRef(agent.model);
-		if (parsed) {
-			return { modelRef: agent.model, ...parsed };
-		}
+		const concrete = toConcrete(agent.model);
+		if (concrete) return concrete;
 	}
 
 	if (!parentModel || parentModel.provider === "router") return undefined;
-	const modelRef = `${parentModel.provider}/${parentModel.id}`;
-	const parsed = parseModelRef(modelRef);
-	if (!parsed) return undefined;
-	return { modelRef, ...parsed };
+	return toConcrete(`${parentModel.provider}/${parentModel.id}`);
 }

package/.pi/lib/harness-subagents-bridge.ts

@@ -35,6 +35,10 @@ import {
 	recordSpawnStart,
 } from "./harness-spawn-budget.js";
 import { parseSpawnContextFromTask } from "./harness-spawn-parse.js";
+import {
+	getRememberedSessionWebArtifactDir,
+	resolveWebArtifactScope,
+} from "./harness-web/artifacts.js";
 import {
 	isUsableApiKey,
 	resolveConcreteSubagentModel,
@@ -130,6 +134,23 @@ export function createHarnessSubagentsExtension(
 				HARNESS_PKG_ROOT: packageRoot,
 				HARNESS_PROJECT_ROOT: projectRoot,
 			};
+			if (agent.name.startsWith("harness/web-retrieval/")) {
+				const ctx = parseSpawnContextFromTask(task);
+				const remembered = getRememberedSessionWebArtifactDir(lastSessionId);
+				if (remembered) {
+					base.HARNESS_WEB_ARTIFACT_DIR = remembered;
+				} else if (ctx?.run_id) {
+					base.HARNESS_WEB_ARTIFACT_DIR = resolveWebArtifactScope({
+						projectRoot,
+						explicitArtifactDir: `.web/runs/${ctx.run_id}`,
+					}).artifactDir;
+				} else {
+					base.HARNESS_WEB_ARTIFACT_DIR = resolveWebArtifactScope({
+						projectRoot,
+						piSessionId: lastSessionId,
+					}).artifactDir;
+				}
+			}
 			const ctx = parseSpawnContextFromTask(task);
 			if (!ctx?.run_id) return base;
 			if (spawnCircuitOpen(ctx.run_id)) {

package/.pi/lib/harness-web/artifacts.ts

@@ -0,0 +1,200 @@
+/**
+ * WRS workspace paths — flat `.web/` aliases + optional per-run/session isolation.
+ * Search/fetch payloads are pooled under `.web/cache/` (see cache.ts).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { activeRunPointerPath } from "../harness-run-context.js";
+import { WEB_ROOT, webCacheHint } from "./cache.js";
+
+export type WebArtifactScopeSource =
+	| "explicit"
+	| "run"
+	| "session"
+	| "workspace";
+
+export interface WebArtifactScope {
+	/** Relative path under repo root, e.g. `.web` or `.web/runs/abc` */
+	artifactDir: string;
+	scopeId: string;
+	source: WebArtifactScopeSource;
+}
+
+function webIsolateEnabled(): boolean {
+	return (
+		process.env.HARNESS_WEB_ISOLATE === "1" ||
+		process.env.HARNESS_WEB_LEGACY_SCOPE === "1"
+	);
+}
+
+/** Parent session → last resolved artifact dir (for web-retrieval subagent env). */
+const sessionArtifactDirs = new Map<string, string>();
+
+const CANONICAL_BASENAMES = new Set([
+	"angles.yaml",
+	"angles-inline.yaml",
+	"search-deep.json",
+	"search.json",
+	"evidence-bundle.json",
+	"answer.md",
+	"highlights.json",
+	"page.md",
+	"map.json",
+]);
+
+export function sanitizeWebScopeId(id: string): string {
+	return id.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 120);
+}
+
+export function isScopedWebArtifactPath(path: string): boolean {
+	const n = path.replace(/\\/g, "/");
+	if (!n.startsWith(`${WEB_ROOT}/`)) return false;
+	const rest = n.slice(`${WEB_ROOT}/`.length);
+	const top = rest.split("/")[0];
+	return top === "runs" || top === "sessions";
+}
+
+function readActiveHarnessRunId(projectRoot: string): string | null {
+	const pointerPath = activeRunPointerPath(projectRoot);
+	if (!existsSync(pointerPath)) return null;
+	try {
+		const raw = readFileSync(pointerPath, "utf-8");
+		const data = JSON.parse(raw) as { run_id?: string };
+		const runId = data.run_id?.trim();
+		return runId || null;
+	} catch {
+		return null;
+	}
+}
+
+export function resolveWebArtifactScope(options: {
+	projectRoot: string;
+	piSessionId?: string;
+	explicitScope?: string;
+	explicitArtifactDir?: string;
+}): WebArtifactScope {
+	const explicitDir =
+		options.explicitArtifactDir?.trim() ||
+		options.explicitScope?.trim() ||
+		process.env.HARNESS_WEB_ARTIFACT_DIR?.trim() ||
+		process.env.HARNESS_WEB_SCOPE?.trim();
+	if (explicitDir) {
+		const normalized = normalizeArtifactDir(explicitDir);
+		return {
+			artifactDir: normalized,
+			scopeId: normalized.split("/").pop() ?? normalized,
+			source: "explicit",
+		};
+	}
+
+	if (webIsolateEnabled()) {
+		const runId =
+			process.env.HARNESS_RUN_ID?.trim() ||
+			readActiveHarnessRunId(options.projectRoot);
+		if (runId) {
+			const id = sanitizeWebScopeId(runId);
+			return {
+				artifactDir: `${WEB_ROOT}/runs/${id}`,
+				scopeId: id,
+				source: "run",
+			};
+		}
+
+		const sessionId = options.piSessionId?.trim();
+		if (sessionId) {
+			const id = sanitizeWebScopeId(sessionId);
+			return {
+				artifactDir: `${WEB_ROOT}/sessions/${id}`,
+				scopeId: id,
+				source: "session",
+			};
+		}
+	}
+
+	return {
+		artifactDir: WEB_ROOT,
+		scopeId: "workspace",
+		source: "workspace",
+	};
+}
+
+export function normalizeArtifactDir(dir: string): string {
+	let n = dir.replace(/\\/g, "/").trim();
+	if (n.startsWith("./")) n = n.slice(2);
+	if (n === WEB_ROOT || n === `${WEB_ROOT}/`) return WEB_ROOT;
+	if (!n.startsWith(`${WEB_ROOT}/`)) {
+		n = `${WEB_ROOT}/${n.replace(/^\/+/, "")}`;
+	}
+	return n.replace(/\/+$/, "");
+}
+
+export function scopedWebArtifactPath(
+	artifactDir: string,
+	basename: string,
+): string {
+	const base = normalizeArtifactDir(artifactDir);
+	if (base === WEB_ROOT) return `${WEB_ROOT}/${basename}`;
+	return `${base}/${basename}`;
+}
+
+/**
+ * Resolve output path: honor explicit paths; optional isolation rewrites flat canonical names.
+ */
+export function resolveWebOutputPath(options: {
+	projectRoot: string;
+	piSessionId?: string;
+	basename: string;
+	explicitOutput?: string;
+	webScope?: string;
+}): { path: string; artifactDir: string; scope: WebArtifactScope } {
+	const scope = resolveWebArtifactScope({
+		projectRoot: options.projectRoot,
+		piSessionId: options.piSessionId,
+		explicitScope: options.webScope,
+	});
+
+	const explicit = options.explicitOutput?.trim();
+	if (explicit) {
+		const norm = explicit.replace(/\\/g, "/");
+		if (isScopedWebArtifactPath(norm)) {
+			const artifactDir = norm.slice(0, norm.lastIndexOf("/"));
+			return { path: norm, artifactDir, scope };
+		}
+		const base = norm.split("/").pop() ?? norm;
+		if (
+			webIsolateEnabled() &&
+			scope.source !== "workspace" &&
+			norm.startsWith(`${WEB_ROOT}/`) &&
+			CANONICAL_BASENAMES.has(base)
+		) {
+			const path = scopedWebArtifactPath(scope.artifactDir, base);
+			return { path, artifactDir: scope.artifactDir, scope };
+		}
+		return { path: norm, artifactDir: scope.artifactDir, scope };
+	}
+
+	const path = scopedWebArtifactPath(scope.artifactDir, options.basename);
+	return { path, artifactDir: scope.artifactDir, scope };
+}
+
+export function rememberSessionWebArtifactDir(
+	sessionId: string,
+	artifactDir: string,
+): void {
+	if (!sessionId?.trim() || !artifactDir?.trim()) return;
+	sessionArtifactDirs.set(sessionId.trim(), normalizeArtifactDir(artifactDir));
+}
+
+export function getRememberedSessionWebArtifactDir(
+	sessionId: string,
+): string | undefined {
+	return sessionArtifactDirs.get(sessionId.trim());
+}
+
+export function webArtifactScopeHint(scope: WebArtifactScope): string {
+	const isolateNote = webIsolateEnabled()
+		? `Isolation on (${scope.artifactDir}/). Set HARNESS_WEB_ISOLATE=0 for shared workspace only.`
+		: `Shared workspace ${scope.artifactDir}/ for angles, search-deep, answer.md. Set HARNESS_WEB_ISOLATE=1 to isolate per session/run.`;
+	return `[WRS workspace] ${isolateNote} ${webCacheHint()}`;
+}