@hadooppei/hwcode 1.0.7 → 1.0.9

package/.pi/lib/knowledge/store.ts

@@ -0,0 +1,365 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmodSync, copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync,
+  statSync, writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import { userRuntimePaths } from "../runtime/paths.ts";
+import { compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
+import type {
+  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeManifest, KnowledgeReviewCursor,
+  KnowledgeReviewTask, KnowledgeScope, KnowledgeSnapshot, KnowledgeTrack, PersistKnowledgeResult,
+} from "./types.ts";
+
+const STORAGE = KNOWLEDGE_RUNTIME_DEFAULTS.storage;
+const SAFE_ID_RE = /^[a-z0-9][a-z0-9-]{0,79}$/u;
+const SAFE_GENERATION_RE = /^[0-9TZ-]+-[a-f0-9]{12}$/u;
+const PROJECT_SCOPE_RE = /^project:[a-f0-9]{16}$/u;
+
+export class KnowledgeCommitBusyError extends Error {}
+
+function emptyCatalog(): KnowledgeCatalog {
+  return { version: 3, updatedAt: new Date().toISOString(), items: [] };
+}
+
+function emptyManifest(): KnowledgeManifest {
+  return {
+    version: 3, generationId: "", createdAt: new Date().toISOString(), leaderToken: "",
+    catalog: emptyCatalog(), reviews: {},
+  };
+}
+
+function ensureDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  chmodSync(path, 0o700);
+}
+
+function atomicWrite(path: string, content: string): void {
+  ensureDirectory(dirname(path));
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+  renameSync(temporary, path);
+  chmodSync(path, 0o600);
+}
+
+export function ensureKnowledgeDirectories(home = homedir()): void {
+  const paths = userRuntimePaths(home);
+  for (const path of [paths.knowledge, paths.knowledgeGenerations, paths.knowledgeRuntime]) ensureDirectory(path);
+}
+
+export function projectKnowledgeKey(projectRoot: string): string {
+  return createHash("sha256").update(resolve(projectRoot)).digest("hex").slice(0, 16);
+}
+
+function generationDirectory(generationId: string, home: string): string | undefined {
+  if (!SAFE_GENERATION_RE.test(generationId)) return undefined;
+  const root = resolve(userRuntimePaths(home).knowledgeGenerations);
+  const directory = resolve(root, generationId);
+  return directory.startsWith(`${root}${sep}`) ? directory : undefined;
+}
+
+function parseManifest(path: string): KnowledgeManifest | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as KnowledgeManifest;
+    if (parsed.version !== 3 || !SAFE_GENERATION_RE.test(parsed.generationId)
+      || parsed.catalog?.version !== 3 || !Array.isArray(parsed.catalog.items)
+      || !parsed.reviews || typeof parsed.reviews !== "object") return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function validManifestAt(manifest: KnowledgeManifest, directory: string): boolean {
+  return manifest.catalog.items.every((entry) => {
+    if (!SAFE_ID_RE.test(entry.id) || basename(entry.file) !== `${entry.id}.md`) return false;
+    if (entry.scope !== "global" && !PROJECT_SCOPE_RE.test(entry.scope)) return false;
+    const path = resolve(directory, entry.file);
+    return path.startsWith(`${directory}${sep}`) && existsSync(path);
+  });
+}
+
+function validManifest(manifest: KnowledgeManifest, home: string): boolean {
+  const directory = generationDirectory(manifest.generationId, home);
+  return Boolean(directory && validManifestAt(manifest, directory));
+}
+
+export function loadCurrentManifest(home = homedir()): KnowledgeManifest {
+  ensureKnowledgeDirectories(home);
+  const paths = userRuntimePaths(home);
+  const preferred = existsSync(paths.knowledgeCurrent) ? readFileSync(paths.knowledgeCurrent, "utf8").trim() : "";
+  const candidates = [preferred, ...readdirSync(paths.knowledgeGenerations, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && SAFE_GENERATION_RE.test(entry.name))
+    .map((entry) => entry.name).sort().reverse()]
+    .filter((value, index, values) => value && values.indexOf(value) === index);
+  for (const generationId of candidates) {
+    const directory = generationDirectory(generationId, home);
+    if (!directory) continue;
+    const manifest = parseManifest(join(directory, "manifest.json"));
+    if (manifest && manifest.generationId === generationId && validManifest(manifest, home)) return manifest;
+  }
+  return emptyManifest();
+}
+
+export function loadKnowledgeCatalog(home = homedir()): KnowledgeCatalog {
+  return loadCurrentManifest(home).catalog;
+}
+
+function normalizeSlug(value: string): string {
+  return value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "").slice(0, STORAGE.slugMaxChars) || "knowledge";
+}
+
+function normalizedFingerprint(candidate: KnowledgeCandidate): string {
+  return createHash("sha256").update(`${candidate.scope}\0${candidate.key.trim().toLowerCase()}`).digest("hex");
+}
+
+function contentHash(candidate: KnowledgeCandidate): string {
+  return createHash("sha256").update(`${candidate.title}\0${candidate.summary}\0${candidate.body}`).digest("hex");
+}
+
+function asStringArray(value: unknown, maxItems: number): string[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item): item is string => typeof item === "string")
+    .map((item) => compactKnowledgeText(item, 240)).filter(Boolean))].slice(0, maxItems);
+}
+
+function normalizeCandidate(value: unknown, projectKey: string): KnowledgeCandidate | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.key !== "string" || typeof raw.title !== "string" || typeof raw.summary !== "string"
+    || typeof raw.body !== "string" || typeof raw.confidence !== "number") return undefined;
+  if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence) return undefined;
+  const explicitUserDirective = raw.explicitUserDirective === true;
+  const scope: KnowledgeScope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
+  const body = compactKnowledgeText(raw.body, 20_000);
+  const evidence = asStringArray(raw.evidence, 8);
+  if (!body || evidence.length === 0) return undefined;
+  const requestedTrack: KnowledgeTrack = raw.storageHint === "rule" ? "rule" : "topic";
+  const ruleEligible = body.length <= STORAGE.maxRuleChars && body.split("\n").length <= STORAGE.maxRuleFileLines
+    && (explicitUserDirective || raw.confidence >= 0.9);
+  return {
+    key: compactKnowledgeText(raw.key, 160), title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
+    summary: compactKnowledgeText(raw.summary, STORAGE.maxSummaryChars),
+    keywords: asStringArray(raw.keywords, STORAGE.maxKeywordCount).map((keyword) => keyword.toLowerCase()),
+    scope, body, evidence, confidence: Math.min(1, raw.confidence),
+    storageHint: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
+    action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
+    explicitUserDirective,
+  };
+}
+
+function renderKnowledgeFile(candidate: KnowledgeCandidate): string {
+  if (candidate.storageHint === "rule") return `# ${candidate.title}\n\n${candidate.body}\n`;
+  return [
+    `# ${candidate.title}`, "", candidate.summary, "", `Keywords: ${candidate.keywords.join(", ")}`, "",
+    candidate.body, "", "## Evidence", "", ...candidate.evidence.map((item) => `- ${item}`), "",
+  ].join("\n");
+}
+
+function applicable(entry: KnowledgeCatalogEntry, projectKey: string): boolean {
+  return entry.scope === "global" || entry.scope === `project:${projectKey}`;
+}
+
+function generateMemory(catalog: KnowledgeCatalog, projectKey?: string): string {
+  const lines = [
+    "# HWCode Knowledge Index", "",
+    "Detailed topics are loaded only through hwcode_knowledge_lookup. Search by ID or keywords.", "",
+  ];
+  const topics = catalog.items.filter((item) => item.track === "topic" && (!projectKey || applicable(item, projectKey)))
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+  for (const item of topics) {
+    const scope = item.scope === "global" ? "global" : "project";
+    const line = `- [${item.id}] (${scope}; ${item.keywords.join(", ")}) ${item.title}: ${item.summary}`;
+    if (lines.length + 1 >= STORAGE.maxMemoryLines || [...lines, line].join("\n").length > STORAGE.maxMemoryChars) {
+      lines.push("- Additional topics remain searchable through hwcode_knowledge_lookup(query: \"keywords\").");
+      break;
+    }
+    lines.push(line);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function processExists(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function acquireCommitLock(leaderToken: string, home: string): () => void {
+  const paths = userRuntimePaths(home);
+  ensureDirectory(paths.knowledgeRuntime);
+  const attempt = (): boolean => {
+    try {
+      mkdirSync(paths.knowledgeCommitLock, { mode: 0o700 });
+      writeFileSync(join(paths.knowledgeCommitLock, "owner.json"), JSON.stringify({ pid: process.pid, leaderToken }), { mode: 0o600 });
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      return false;
+    }
+  };
+  if (!attempt()) {
+    try {
+      const owner = JSON.parse(readFileSync(join(paths.knowledgeCommitLock, "owner.json"), "utf8")) as {
+        pid?: number; leaderToken?: string;
+      };
+      if (owner.leaderToken !== leaderToken || (typeof owner.pid === "number" && !processExists(owner.pid))) {
+        rmSync(paths.knowledgeCommitLock, { recursive: true, force: true });
+      }
+    } catch {
+      const age = Date.now() - statSync(paths.knowledgeCommitLock).mtimeMs;
+      if (age > KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs) rmSync(paths.knowledgeCommitLock, { recursive: true, force: true });
+    }
+    if (!attempt()) throw new KnowledgeCommitBusyError("Knowledge repository is busy");
+  }
+  return () => rmSync(paths.knowledgeCommitLock, { recursive: true, force: true });
+}
+
+function newGenerationId(): string {
+  return `${new Date().toISOString().replace(/[:.]/gu, "-")}-${randomUUID().replace(/-/gu, "").slice(0, 12)}`;
+}
+
+function copyCurrentContent(manifest: KnowledgeManifest, target: string, home: string): void {
+  for (const name of ["rules", "topics", "pending"]) ensureDirectory(join(target, name));
+  if (!manifest.generationId) return;
+  const source = generationDirectory(manifest.generationId, home);
+  if (!source) return;
+  for (const name of ["rules", "topics", "pending"]) {
+    const sourceDirectory = join(source, name);
+    if (!existsSync(sourceDirectory)) continue;
+    for (const entry of readdirSync(sourceDirectory, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const sourceFile = join(sourceDirectory, entry.name);
+      const targetFile = join(target, name, entry.name);
+      try { linkSync(sourceFile, targetFile); } catch { copyFileSync(sourceFile, targetFile); }
+    }
+  }
+}
+
+function storedRuleCharacters(directory: string): number {
+  return readdirSync(join(directory, "rules"), { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .reduce((total, entry) => total + readFileSync(join(directory, "rules", entry.name), "utf8").length, 0);
+}
+
+function reviewCursor(task: KnowledgeReviewTask): KnowledgeReviewCursor {
+  return {
+    sessionId: task.sessionId, sessionKey: task.sessionKey, sessionFileHash: task.sessionFileHash,
+    projectRoot: task.projectRoot, projectKey: task.projectKey, lastReviewedEntryId: task.lastEntryId,
+    lastReviewedAt: new Date().toISOString(), lastDeltaDigest: task.deltaDigest,
+    lastReviewKey: task.reviewKey, fileSize: task.fileSize, fileMtimeMs: task.fileMtimeMs,
+  };
+}
+
+export function commitKnowledgeReview(
+  values: unknown[], task: KnowledgeReviewTask, leaderToken: string, home = homedir(),
+): PersistKnowledgeResult {
+  ensureKnowledgeDirectories(home);
+  const release = acquireCommitLock(leaderToken, home);
+  const paths = userRuntimePaths(home);
+  let temporary = "";
+  try {
+    const current = loadCurrentManifest(home);
+    if (current.reviews[task.sessionKey]?.lastReviewKey === task.reviewKey) {
+      return { saved: 0, updated: 0, pending: 0, skipped: 0 };
+    }
+    const generationId = newGenerationId();
+    temporary = join(paths.knowledgeGenerations, `.tmp-${generationId}-${process.pid}`);
+    ensureDirectory(temporary);
+    copyCurrentContent(current, temporary, home);
+    const catalog: KnowledgeCatalog = structuredClone(current.catalog);
+    const result: PersistKnowledgeResult = { saved: 0, updated: 0, pending: 0, skipped: 0 };
+    for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
+      const candidate = normalizeCandidate(value, task.projectKey);
+      if (!candidate) { result.skipped++; continue; }
+      const fingerprint = normalizedFingerprint(candidate);
+      const hash = contentHash(candidate);
+      const existingIndex = catalog.items.findIndex((item) => item.fingerprint === fingerprint);
+      const existing = existingIndex >= 0 ? catalog.items[existingIndex] : undefined;
+      if (existing?.contentHash === hash) {
+        existing.evidenceCount += candidate.evidence.length;
+        existing.updatedAt = new Date().toISOString();
+        result.updated++;
+        continue;
+      }
+      if (existing && !(candidate.action === "revise" && (candidate.explicitUserDirective || candidate.confidence >= 0.92))) {
+        const name = `${Date.now()}-${normalizeSlug(candidate.title)}-${randomUUID().slice(0, 8)}.json`;
+        atomicWrite(join(temporary, "pending", name), `${JSON.stringify({ reason: "conflicting-or-ambiguous-update", candidate }, null, 2)}\n`);
+        result.pending++;
+        continue;
+      }
+      if (!existing && candidate.storageHint === "rule"
+        && storedRuleCharacters(temporary) + renderKnowledgeFile(candidate).length > STORAGE.maxRulesPromptChars) {
+        candidate.storageHint = "topic";
+      }
+      const now = new Date().toISOString();
+      const id = existing?.id ?? `${normalizeSlug(candidate.title)}-${fingerprint.slice(0, 8)}`;
+      const track = existing?.track ?? candidate.storageHint;
+      candidate.storageHint = track;
+      const relativeFile = `${track === "rule" ? "rules" : "topics"}/${id}.md`;
+      atomicWrite(join(temporary, relativeFile), renderKnowledgeFile(candidate));
+      const entry: KnowledgeCatalogEntry = {
+        id, fingerprint, contentHash: hash, title: candidate.title, summary: candidate.summary,
+        keywords: candidate.keywords, scope: candidate.scope, track, file: relativeFile,
+        evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
+        createdAt: existing?.createdAt ?? now, updatedAt: now,
+      };
+      if (existingIndex >= 0) { catalog.items[existingIndex] = entry; result.updated++; }
+      else { catalog.items.push(entry); result.saved++; }
+    }
+    catalog.updatedAt = new Date().toISOString();
+    const manifest: KnowledgeManifest = {
+      version: 3, generationId, createdAt: new Date().toISOString(), leaderToken, catalog,
+      reviews: { ...current.reviews, [task.sessionKey]: reviewCursor(task) },
+    };
+    atomicWrite(join(temporary, "MEMORY.md"), generateMemory(catalog));
+    atomicWrite(join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    if (!validManifestAt(manifest, temporary)) throw new Error("Refusing to publish an incomplete knowledge generation");
+    const finalDirectory = join(paths.knowledgeGenerations, generationId);
+    renameSync(temporary, finalDirectory);
+    temporary = "";
+    atomicWrite(paths.knowledgeCurrent, `${generationId}\n`);
+    return result;
+  } finally {
+    if (temporary) rmSync(temporary, { recursive: true, force: true });
+    release();
+  }
+}
+
+function readCatalogFile(entry: KnowledgeCatalogEntry, manifest: KnowledgeManifest, home: string): string | undefined {
+  if (!SAFE_ID_RE.test(entry.id) || basename(entry.file) !== `${entry.id}.md`) return undefined;
+  const root = generationDirectory(manifest.generationId, home);
+  if (!root) return undefined;
+  const path = resolve(root, entry.file);
+  if (!path.startsWith(`${root}${sep}`) || !existsSync(path)) return undefined;
+  return sanitizeKnowledgeText(readFileSync(path, "utf8"));
+}
+
+export function loadKnowledgeSnapshot(projectKey: string, home = homedir()): KnowledgeSnapshot {
+  const manifest = loadCurrentManifest(home);
+  if (!manifest.generationId) {
+    return { rulesPrompt: "", memoryPrompt: generateMemory(manifest.catalog, projectKey), catalog: manifest.catalog };
+  }
+  const rules = manifest.catalog.items.filter((entry) => entry.track === "rule" && applicable(entry, projectKey))
+    .sort((left, right) => left.file.localeCompare(right.file))
+    .map((entry) => readCatalogFile(entry, manifest, home)).filter((content): content is string => Boolean(content));
+  return {
+    generationId: manifest.generationId, rulesPrompt: rules.join("\n\n"),
+    memoryPrompt: generateMemory(manifest.catalog, projectKey), catalog: manifest.catalog,
+  };
+}
+
+export function loadKnowledgeById(
+  id: string, projectKey: string, home = homedir(),
+): { entry: KnowledgeCatalogEntry; content: string } | undefined {
+  if (!SAFE_ID_RE.test(id)) return undefined;
+  const manifest = loadCurrentManifest(home);
+  const entry = manifest.catalog.items.find((item) => item.id === id && applicable(item, projectKey));
+  if (!entry) return undefined;
+  const content = readCatalogFile(entry, manifest, home);
+  return content ? { entry, content } : undefined;
+}

package/.pi/lib/knowledge/types.ts

@@ -0,0 +1,91 @@
+export type KnowledgeTrack = "rule" | "topic";
+export type KnowledgeScope = "global" | `project:${string}`;
+export type KnowledgeAction = "add" | "reinforce" | "revise";
+
+export interface KnowledgeCandidate {
+  key: string;
+  title: string;
+  summary: string;
+  keywords: string[];
+  scope: KnowledgeScope;
+  body: string;
+  evidence: string[];
+  confidence: number;
+  storageHint: KnowledgeTrack;
+  action: KnowledgeAction;
+  explicitUserDirective: boolean;
+}
+
+export interface KnowledgeCatalogEntry {
+  id: string;
+  fingerprint: string;
+  contentHash: string;
+  title: string;
+  summary: string;
+  keywords: string[];
+  scope: KnowledgeScope;
+  track: KnowledgeTrack;
+  file: string;
+  evidenceCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface KnowledgeCatalog {
+  version: 3;
+  updatedAt: string;
+  items: KnowledgeCatalogEntry[];
+}
+
+export interface KnowledgeSnapshot {
+  generationId?: string;
+  rulesPrompt: string;
+  memoryPrompt: string;
+  catalog: KnowledgeCatalog;
+}
+
+export interface KnowledgeReviewCursor {
+  sessionId: string;
+  sessionKey: string;
+  sessionFileHash: string;
+  projectRoot: string;
+  projectKey: string;
+  lastReviewedEntryId?: string;
+  lastReviewedAt?: string;
+  lastDeltaDigest: string;
+  lastReviewKey: string;
+  fileSize: number;
+  fileMtimeMs: number;
+}
+
+export interface KnowledgeManifest {
+  version: 3;
+  generationId: string;
+  createdAt: string;
+  leaderToken: string;
+  catalog: KnowledgeCatalog;
+  reviews: Record<string, KnowledgeReviewCursor>;
+}
+
+export interface PersistKnowledgeResult {
+  saved: number;
+  updated: number;
+  pending: number;
+  skipped: number;
+}
+
+export interface KnowledgeReviewTask {
+  requestId: string;
+  reviewKey: string;
+  sessionId: string;
+  sessionKey: string;
+  sessionFileHash: string;
+  projectRoot: string;
+  projectKey: string;
+  firstEntryId: string;
+  lastEntryId: string;
+  delta: string;
+  deltaDigest: string;
+  fileSize: number;
+  fileMtimeMs: number;
+}

package/.pi/lib/knowledge/worker-protocol.ts

@@ -0,0 +1,20 @@
+import type { KnowledgeReviewTask, PersistKnowledgeResult } from "./types.ts";
+
+export type KnowledgeWorkerInput =
+  | { type: "configure"; modelAvailable: boolean; sessionsRoot: string }
+  | { type: "review_result"; leaderToken: string; requestId: string; raw?: string; error?: string }
+  | { type: "scan_now" }
+  | { type: "stop" };
+
+export type KnowledgeWorkerOutput =
+  | { type: "leadership"; state: "leader" | "standby" | "ineligible"; leaderToken?: string }
+  | { type: "review_request"; leaderToken: string; requestId: string; task: KnowledgeReviewTask }
+  | { type: "review_cancel"; requestId: string; reason: string }
+  | { type: "review_saved"; requestId: string; generationId?: string; result: PersistKnowledgeResult }
+  | { type: "review_failed"; requestId?: string; error: string }
+  | { type: "generation_changed"; generationId: string };
+
+export interface CoordinatorBroadcast {
+  type: "generation_changed";
+  generationId: string;
+}

package/.pi/lib/runtime/defaults.ts

@@ -18,3 +18,34 @@ export const CLOUD_RUNTIME_DEFAULTS = Object.freeze({
   templates: Object.freeze({ slugMaxLength: 48, nameMaxLength: 80 }),
   terraform: Object.freeze({ executable: "terraform", planFile: "hwcode.tfplan" }),
 });
+
+/**
+ * Defaults for the cross-workflow knowledge base (`~/.hwcode/knowledge-v3/`).
+ *
+ * A Worker checks settled sessions on a fixed interval. Short rules are loaded
+ * in full; detailed topics are routed through a bounded MEMORY.md index so the
+ * prompt cost stays stable as the complete machine catalog grows.
+ */
+export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
+  review: Object.freeze({
+    intervalMs: 60_000,
+    idleMs: 60_000,
+    capabilityPollMs: 5_000,
+    modelTimeoutMs: 120_000,
+    maxDeltaChars: 30_000,
+    maxCandidates: 8,
+    minimumConfidence: 0.72,
+  }),
+  storage: Object.freeze({
+    maxRuleChars: 600,
+    maxRuleFileLines: 40,
+    maxRulesPromptChars: 12_000,
+    maxMemoryChars: 25_000,
+    maxMemoryLines: 200,
+    maxSummaryChars: 180,
+    maxTitleChars: 100,
+    maxKeywordCount: 12,
+    maxLookupResults: 5,
+    slugMaxChars: 64,
+  }),
+});

package/.pi/lib/runtime/paths.ts

@@ -5,6 +5,15 @@ export const HWCODE_DATA_DIRECTORY = ".hwcode";
 export const PROJECT_SDD_SPECS_RELATIVE = `${HWCODE_DATA_DIRECTORY}/specs`;
 export const PROJECT_CLOUD_RUNS_RELATIVE = `${HWCODE_DATA_DIRECTORY}/cloud/runs`;
 
+// Canonical subpath layout under ~/.hwcode. Kept together so filesystem topology
+// stays in one place instead of scattered across cloud/knowledge modules.
+const CLOUD_SUBDIR = "cloud";
+const CLOUD_VAULT_FILE = "credentials.enc";
+const CLOUD_KNOWN_HOSTS_FILE = "known_hosts";
+const CLOUD_TEMPLATES_SUBDIR = "templates";
+const CLOUD_TERRAFORM_SUBDIR = "terraform";
+const KNOWLEDGE_SUBDIR = "knowledge-v3";
+
 export interface ProjectRuntimePaths {
   root: string;
   hwcode: string;
@@ -18,14 +27,21 @@ export interface UserRuntimePaths {
   cloud: string;
   cloudVault: string;
   cloudKnownHosts: string;
-  cloudPromptTemplates: string;
-  cloudDeploymentTemplates: string;
+  cloudTerraformTemplates: string;
+  knowledge: string;
+  knowledgeGenerations: string;
+  knowledgeCurrent: string;
+  knowledgeRuntime: string;
+  knowledgeCoordinatorSocket: string;
+  knowledgeLeader: string;
+  knowledgeCommitLock: string;
+  knowledgeElectionLock: string;
 }
 
 export function projectRuntimePaths(projectRoot: string): ProjectRuntimePaths {
   const root = resolve(projectRoot);
   const hwcode = join(root, HWCODE_DATA_DIRECTORY);
-  const cloud = join(hwcode, "cloud");
+  const cloud = join(hwcode, CLOUD_SUBDIR);
   return {
     root,
     hwcode,
@@ -37,25 +53,26 @@ export function projectRuntimePaths(projectRoot: string): ProjectRuntimePaths {
 
 export function userRuntimePaths(home = homedir()): UserRuntimePaths {
   const root = join(home, HWCODE_DATA_DIRECTORY);
-  const cloud = join(root, "cloud");
+  const cloud = join(root, CLOUD_SUBDIR);
+  const knowledge = join(root, KNOWLEDGE_SUBDIR);
   return {
     root,
     cloud,
-    cloudVault: join(cloud, "credentials.enc"),
-    cloudKnownHosts: join(cloud, "known_hosts"),
-    cloudPromptTemplates: join(cloud, "templates", "prompts"),
-    cloudDeploymentTemplates: join(cloud, "templates", "deployments"),
+    cloudVault: join(cloud, CLOUD_VAULT_FILE),
+    cloudKnownHosts: join(cloud, CLOUD_KNOWN_HOSTS_FILE),
+    cloudTerraformTemplates: join(cloud, CLOUD_TEMPLATES_SUBDIR, CLOUD_TERRAFORM_SUBDIR),
+    knowledge,
+    knowledgeGenerations: join(knowledge, "generations"),
+    knowledgeCurrent: join(knowledge, "CURRENT"),
+    knowledgeRuntime: join(knowledge, "runtime"),
+    // Unix-domain socket paths are short on purpose (macOS caps them at roughly 104 bytes).
+    knowledgeCoordinatorSocket: join(root, "knowledge-v3.sock"),
+    knowledgeLeader: join(knowledge, "runtime", "leader.json"),
+    knowledgeCommitLock: join(knowledge, "runtime", "commit.lock"),
+    knowledgeElectionLock: join(knowledge, "runtime", "election.lock"),
   };
 }
 
-export function legacyUserCloudTemplatePaths(home = homedir()): {
-  prompts: string;
-  deployments: string;
-} {
-  const cloud = join(home, HWCODE_DATA_DIRECTORY, "cloud");
-  return { prompts: join(cloud, "prompts"), deployments: join(cloud, "templates") };
-}
-
 export function remoteRunnerPaths(user: string): { root: string; runs: string } {
   const root = posix.join("/home", user, HWCODE_DATA_DIRECTORY);
   return { root, runs: posix.join(root, "runs") };

package/.pi/lib/tool-result.ts

@@ -0,0 +1,7 @@
+export function toolError(message: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text: message }], isError: true, details };
+}
+
+export function toolOk(message: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text: message }], details };
+}