@hadooppei/hwcode 1.0.24 → 1.0.25

package/.pi/dist/lib/knowledge/evidence.js

@@ -299,5 +299,5 @@ export function buildKnowledgeEpisodes(evidence) {
         ? episodes.filter((episode) => !episode.id.includes("-general-reusable-work-") || episode.userSignal)
         : episodes;
     return retained.sort((left, right) => right.score - left.score || right.evidenceIds.length - left.evidenceIds.length)
-        .slice(0, 6);
+        .slice(0, 2);
 }

package/.pi/dist/lib/knowledge/extractor.js

@@ -14,14 +14,16 @@ Treat failed, unsupported, invalid, or corrected operations as negative evidence
 Use storageHint "rule" only for one short imperative instruction of at most 240 characters. A rule must not contain incident narration, example resource names, IDs, timestamps, or evidence details. Use "topic" for multi-step SOPs and detailed experience.
 Rank knowledge by future time saved, repeated failures, hypothesis reversals, user corrections, verified resolution, reuse, and novelty. Do not favor the final task result merely because it completed the objective. Every supplied episode scoring 45 or higher must have an episodeDecisions entry, even when skipped.
 Relevant existing knowledge may be supplied. Cheap recall only proposes related items; it does not prove duplication. Compare execution environment, symptom, and root cause. Use action "reinforce" only when the exact target already covers every claim and there is no new content. Use "extend" for new compatible claims, "correct" when direct evidence disproves old content, "retire" when the whole target is invalid, and "add" for a distinct environment or root cause. Never turn lexical similarity into reinforcement.
-Prefer the most specific existing topic that already covers a claim over a broad conventions or SOP topic.
+For every candidate, first compare the most specific recalled existing topic. When it covers the same concrete failure environment, symptom, root cause, or verified workaround, you must target that topic with "reinforce", "extend", or "correct" as warranted instead of adding knowledge. Prefer the concrete fault topic over broad conventions, generic SOP topics, or incidental access facts such as a temporary SSH user, port, or resource name.
 Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
 The prior validation context is only for checking facts and contradictions; do not persist it again unless the new delta independently reinforces it. Prefer accumulated workflow successfulSteps and failedApproaches over assistant narration.
 Every technical claim must have a stable claim key and cite evidenceIds from the supplied evidence ledger. Tool success, tool failure, and verification evidence outrank assistant narration. Do not support a service-wide or universal claim with one operation-specific failure. Evidence for an unrelated parameter error cannot support an API-version claim.
-Keep each candidate atomic: put separable claim sets in separate candidates, omit any claim without direct cited evidence, and prioritize the highest-value supported candidates. One unsupported claim rejects its entire candidate.
-Each summary must be one complete sentence of at most 160 characters. Keep each topic body under 2200 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered. Return at most 3 candidates.
+Keep each candidate atomic: put separable claim sets in separate candidates, omit any claim without direct cited evidence, and select only the two highest-value supported information items. One unsupported claim rejects its entire candidate.
+Classify every candidate as exactly one category: "principle" for a durable invariant or rule; "configuration" for a verified setting or parameter contract; "method" for a repeatable procedure; "strategy" for reusable diagnosis or design reasoning; or "caution" for a trap, failure signature, or boundary.
+Return compact JSON intended for a background task: at most 2 candidates; each summary at most 120 characters; each topic body at most 800 characters; each episode decision reason at most 120 characters; and all candidate bodies combined at most 1400 characters. Prefer fewer complete high-value candidates over filling the limit. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered.
 The body must not repeat the title as a Markdown H1. The storage renderer supplies the H1. Replace any necessary example resource value with an obvious placeholder instead of a real project, namespace, image, network, or resource name.
-Return: {"episodeDecisions":[{"episodeId":"ep-id","decision":"add|reinforce|extend|correct|retire|skip","targetId":"existing-id or omitted","reason":"..."}],"candidates":[{"key":"stable semantic key","identityKey":"platform/runtime/problem/root-cause","targetId":"existing-id or null","episodeIds":["ep-id"],"title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body or only the new section for extend","claims":[{"key":"stable claim key","text":"one precise claim","evidenceIds":["ev-id"]}],"evidenceIds":["ev-id"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|extend|correct|retire","explicitUserDirective":false,"durability":"stable"}]}
+Evidence IDs are short handles such as "e1" and "e2". Copy them exactly from the evidence ledger.
+Return: {"episodeDecisions":[{"episodeId":"ep-id","decision":"add|reinforce|extend|correct|retire|skip","targetId":"existing-id or omitted","reason":"..."}],"candidates":[{"key":"stable semantic key","category":"principle|configuration|method|strategy|caution","identityKey":"platform/runtime/problem/root-cause","targetId":"existing-id or null","episodeIds":["ep-id"],"title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body or only the new section for extend","claims":[{"key":"stable claim key","text":"one precise claim","evidenceIds":["e1"]}],"evidenceIds":["e1"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|extend|correct|retire","explicitUserDirective":false,"durability":"stable"}]}
 Return {"episodeDecisions":[],"candidates":[]} only when there are no mandatory episodes and nothing meets the threshold.`;
 export function buildKnowledgeExtractionPrompt(projectRoot, delta, context = "", existing = [], evidence = [], episodes = []) {
     const related = existing.length > 0 ? JSON.stringify(existing) : "[]";

package/.pi/dist/lib/knowledge/session-scanner.js

@@ -312,7 +312,9 @@ export function readReviewTask(sessionFile, cursor, now = Date.now()) {
         return undefined;
     const pendingEntryIds = new Set(pending.map((entry) => entry.id));
     const evidenceWindow = cursorIndex >= 0 ? branch.slice(Math.max(0, cursorIndex - 40)) : pending;
-    const evidence = buildKnowledgeEvidence(evidenceWindow).filter((item) => pendingEntryIds.has(item.entryId));
+    const evidence = buildKnowledgeEvidence(evidenceWindow)
+        .filter((item) => pendingEntryIds.has(item.entryId))
+        .map((item, index) => ({ ...item, id: `e${index + 1}` }));
     const episodes = buildKnowledgeEpisodes(evidence);
     const lookupResultEntryIds = knowledgeLookupResultEntryIds(branch);
     const delta = buildDelta(pending, lookupResultEntryIds);

package/.pi/dist/lib/knowledge/store.js

@@ -11,6 +11,9 @@ const SAFE_GENERATION_RE = /^[0-9TZ-]+-[a-f0-9]{12}$/u;
 const PROJECT_SCOPE_RE = /^project:[a-f0-9]{16}$/u;
 const UNVERIFIED_CLAIM_RE = /(?:待验证|尚未(?:验证|确认)|未经(?:验证|确认)|未(?:经)?证实|推测|猜测|疑似|可能是|可能由于|可能导致|或许|unverified|unconfirmed|speculat(?:e|ive|ion)|hypothes(?:is|ize)|suspect(?:ed|ion)?|possibly|probably)/iu;
 const VOLATILE_ARGUMENT_RE = /--(?:namespace|name|server_name|security_group_id|subnet_id|vpc_id|image_id|project_id)(?:\.\d+)?=(?!<[^>]+>|\$?\{)[^\s`"']+/iu;
+const KNOWLEDGE_CATEGORIES = new Set([
+    "principle", "configuration", "method", "strategy", "caution",
+]);
 export class KnowledgeCommitBusyError extends Error {
 }
 function emptyCatalog() {
@@ -219,6 +222,9 @@ function normalizeCandidate(value, task, validationText) {
     if (typeof raw.key !== "string" || typeof raw.title !== "string" || typeof raw.summary !== "string"
         || typeof raw.body !== "string" || typeof raw.confidence !== "number")
         return { reason: "invalid-schema" };
+    if (typeof raw.category !== "string" || !KNOWLEDGE_CATEGORIES.has(raw.category)) {
+        return { reason: "invalid-schema" };
+    }
     if (raw.durability !== "stable")
         return { reason: "unstable" };
     if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence)
@@ -283,6 +289,7 @@ function normalizeCandidate(value, task, validationText) {
         || raw.action === "retire" ? raw.action : "add";
     return { candidate: {
             key: compactKnowledgeText(raw.key, 160),
+            category: raw.category,
             identityKey: typeof raw.identityKey === "string" ? compactKnowledgeText(raw.identityKey, 240).toLowerCase() : undefined,
             targetId,
             title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
@@ -315,7 +322,8 @@ function renderKnowledgeFile(candidate) {
     if (candidate.storageHint === "rule")
         return `# ${candidate.title}\n\n${candidate.body}\n`;
     return [
-        `# ${candidate.title}`, "", candidate.summary, "", `Keywords: ${candidate.keywords.join(", ")}`, "",
+        `# ${candidate.title}`, "", candidate.summary, "", `Category: ${candidate.category}`,
+        `Keywords: ${candidate.keywords.join(", ")}`, "",
         candidate.body, "", "## Evidence", "", ...candidate.evidence.map((item) => `- ${item}`), "",
     ].join("\n");
 }
@@ -342,7 +350,8 @@ function generateMemory(catalog, 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}`;
+        const category = item.category ? `${item.category}; ` : "";
+        const line = `- [${item.id}] (${category}${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;
@@ -493,6 +502,7 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
                     continue;
                 }
                 existing.evidenceCount += candidate.evidence.length;
+                existing.category ??= candidate.category;
                 existing.updatedAt = new Date().toISOString();
                 result.updated++;
                 continue;
@@ -535,6 +545,7 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
                 existing.contentHash = createHash("sha256").update(content).digest("hex");
                 existing.keywords = [...new Set([...existing.keywords, ...candidate.keywords])].slice(0, STORAGE.maxKeywordCount);
                 existing.claimKeys = [...new Set([...(existing.claimKeys ?? []), ...newClaimKeys])];
+                existing.category ??= candidate.category;
                 existing.evidenceCount += candidate.evidence.length;
                 existing.updatedAt = new Date().toISOString();
                 result.updated++;
@@ -566,7 +577,8 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
             const entry = {
                 id, fingerprint: existing?.fingerprint ?? fingerprint, contentHash: hash,
                 title: candidate.title, summary: candidate.summary,
-                keywords: candidate.keywords, scope: existing?.scope ?? candidate.scope, track, file: relativeFile,
+                keywords: candidate.keywords, category: candidate.category,
+                scope: existing?.scope ?? candidate.scope, track, file: relativeFile,
                 evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
                 identityKey: candidate.identityKey ?? existing?.identityKey,
                 claimKeys: candidate.claims?.map((claim) => claim.key) ?? existing?.claimKeys,

package/.pi/dist/lib/runtime/defaults.js

@@ -43,7 +43,7 @@ export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
         maxExistingContextItems: 8,
         maxExistingBodyItems: 2,
         maxExistingBodyChars: 600,
-        maxCandidates: 3,
+        maxCandidates: 2,
         minimumConfidence: 0.72,
     }),
     storage: Object.freeze({

package/.pi/extensions/knowledge.ts

@@ -208,6 +208,7 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
         title: entry.title,
         summary: entry.summary,
         keywords: entry.keywords,
+        category: entry.category,
         track: entry.track,
         identityKey: entry.identityKey,
         claimKeys: entry.claimKeys,
@@ -254,7 +255,6 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
       },
       {
         signal: controller.signal,
-        reasoningEffort: "low",
         cacheRetention: "none",
         temperature: 0,
         timeoutMs: KNOWLEDGE_RUNTIME_DEFAULTS.review.requestTimeoutMs,

package/.pi/extensions/model-providers.ts

@@ -22,6 +22,7 @@ import {
   type ModelInput,
   type ModelProviderConfig,
 } from "../lib/models/provider-config.ts";
+import { closeOpenAiSseAtDone } from "../lib/models/sse-response.ts";
 
 type OpenAIModel = Model<"openai-completions">;
 
@@ -373,8 +374,14 @@ function createLoginProvider(
         update: () => { models = refreshed; },
       });
     },
-    stream: (model, context, options) => stream(model, context, options as Parameters<typeof stream>[2]),
-    streamSimple: (model, context, options) => streamSimple(model, context, options),
+    stream: (model, context, options) => stream(model, context, {
+      ...options,
+      fetch: closeOpenAiSseAtDone(options?.fetch),
+    } as Parameters<typeof stream>[2]),
+    streamSimple: (model, context, options) => streamSimple(model, context, {
+      ...options,
+      fetch: closeOpenAiSseAtDone(options?.fetch),
+    }),
   };
 }
 

package/.pi/lib/knowledge/evidence.ts

@@ -314,5 +314,5 @@ export function buildKnowledgeEpisodes(evidence: KnowledgeEvidence[]): Knowledge
     ? episodes.filter((episode) => !episode.id.includes("-general-reusable-work-") || episode.userSignal)
     : episodes;
   return retained.sort((left, right) => right.score - left.score || right.evidenceIds.length - left.evidenceIds.length)
-    .slice(0, 6);
+    .slice(0, 2);
 }

package/.pi/lib/knowledge/extractor.ts

@@ -2,13 +2,14 @@ import { createHash } from "node:crypto";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
 import { compactKnowledgeText } from "./sanitize.ts";
-import type { KnowledgeEpisode, KnowledgeEpisodeDecision, KnowledgeEvidence } from "./types.ts";
+import type { KnowledgeCategory, KnowledgeEpisode, KnowledgeEpisodeDecision, KnowledgeEvidence } from "./types.ts";
 
 export interface ExistingKnowledgeContext {
   id: string;
   title: string;
   summary: string;
   keywords: string[];
+  category?: KnowledgeCategory;
   track: "rule" | "topic";
   identityKey?: string;
   claimKeys?: string[];
@@ -33,14 +34,16 @@ Treat failed, unsupported, invalid, or corrected operations as negative evidence
 Use storageHint "rule" only for one short imperative instruction of at most 240 characters. A rule must not contain incident narration, example resource names, IDs, timestamps, or evidence details. Use "topic" for multi-step SOPs and detailed experience.
 Rank knowledge by future time saved, repeated failures, hypothesis reversals, user corrections, verified resolution, reuse, and novelty. Do not favor the final task result merely because it completed the objective. Every supplied episode scoring 45 or higher must have an episodeDecisions entry, even when skipped.
 Relevant existing knowledge may be supplied. Cheap recall only proposes related items; it does not prove duplication. Compare execution environment, symptom, and root cause. Use action "reinforce" only when the exact target already covers every claim and there is no new content. Use "extend" for new compatible claims, "correct" when direct evidence disproves old content, "retire" when the whole target is invalid, and "add" for a distinct environment or root cause. Never turn lexical similarity into reinforcement.
-Prefer the most specific existing topic that already covers a claim over a broad conventions or SOP topic.
+For every candidate, first compare the most specific recalled existing topic. When it covers the same concrete failure environment, symptom, root cause, or verified workaround, you must target that topic with "reinforce", "extend", or "correct" as warranted instead of adding knowledge. Prefer the concrete fault topic over broad conventions, generic SOP topics, or incidental access facts such as a temporary SSH user, port, or resource name.
 Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
 The prior validation context is only for checking facts and contradictions; do not persist it again unless the new delta independently reinforces it. Prefer accumulated workflow successfulSteps and failedApproaches over assistant narration.
 Every technical claim must have a stable claim key and cite evidenceIds from the supplied evidence ledger. Tool success, tool failure, and verification evidence outrank assistant narration. Do not support a service-wide or universal claim with one operation-specific failure. Evidence for an unrelated parameter error cannot support an API-version claim.
-Keep each candidate atomic: put separable claim sets in separate candidates, omit any claim without direct cited evidence, and prioritize the highest-value supported candidates. One unsupported claim rejects its entire candidate.
-Each summary must be one complete sentence of at most 160 characters. Keep each topic body under 2200 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered. Return at most 3 candidates.
+Keep each candidate atomic: put separable claim sets in separate candidates, omit any claim without direct cited evidence, and select only the two highest-value supported information items. One unsupported claim rejects its entire candidate.
+Classify every candidate as exactly one category: "principle" for a durable invariant or rule; "configuration" for a verified setting or parameter contract; "method" for a repeatable procedure; "strategy" for reusable diagnosis or design reasoning; or "caution" for a trap, failure signature, or boundary.
+Return compact JSON intended for a background task: at most 2 candidates; each summary at most 120 characters; each topic body at most 800 characters; each episode decision reason at most 120 characters; and all candidate bodies combined at most 1400 characters. Prefer fewer complete high-value candidates over filling the limit. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered.
 The body must not repeat the title as a Markdown H1. The storage renderer supplies the H1. Replace any necessary example resource value with an obvious placeholder instead of a real project, namespace, image, network, or resource name.
-Return: {"episodeDecisions":[{"episodeId":"ep-id","decision":"add|reinforce|extend|correct|retire|skip","targetId":"existing-id or omitted","reason":"..."}],"candidates":[{"key":"stable semantic key","identityKey":"platform/runtime/problem/root-cause","targetId":"existing-id or null","episodeIds":["ep-id"],"title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body or only the new section for extend","claims":[{"key":"stable claim key","text":"one precise claim","evidenceIds":["ev-id"]}],"evidenceIds":["ev-id"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|extend|correct|retire","explicitUserDirective":false,"durability":"stable"}]}
+Evidence IDs are short handles such as "e1" and "e2". Copy them exactly from the evidence ledger.
+Return: {"episodeDecisions":[{"episodeId":"ep-id","decision":"add|reinforce|extend|correct|retire|skip","targetId":"existing-id or omitted","reason":"..."}],"candidates":[{"key":"stable semantic key","category":"principle|configuration|method|strategy|caution","identityKey":"platform/runtime/problem/root-cause","targetId":"existing-id or null","episodeIds":["ep-id"],"title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body or only the new section for extend","claims":[{"key":"stable claim key","text":"one precise claim","evidenceIds":["e1"]}],"evidenceIds":["e1"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|extend|correct|retire","explicitUserDirective":false,"durability":"stable"}]}
 Return {"episodeDecisions":[],"candidates":[]} only when there are no mandatory episodes and nothing meets the threshold.`;
 
 export function buildKnowledgeExtractionPrompt(

package/.pi/lib/knowledge/session-scanner.ts

@@ -283,7 +283,9 @@ export function readReviewTask(
   if (pending.length === 0) return undefined;
   const pendingEntryIds = new Set(pending.map((entry) => entry.id));
   const evidenceWindow = cursorIndex >= 0 ? branch.slice(Math.max(0, cursorIndex - 40)) : pending;
-  const evidence = buildKnowledgeEvidence(evidenceWindow).filter((item) => pendingEntryIds.has(item.entryId));
+  const evidence = buildKnowledgeEvidence(evidenceWindow)
+    .filter((item) => pendingEntryIds.has(item.entryId))
+    .map((item, index) => ({ ...item, id: `e${index + 1}` }));
   const episodes = buildKnowledgeEpisodes(evidence);
   const lookupResultEntryIds = knowledgeLookupResultEntryIds(branch);
   const delta = buildDelta(pending, lookupResultEntryIds);

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

@@ -10,7 +10,7 @@ import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
 import { userRuntimePaths } from "../runtime/paths.ts";
 import { compactKnowledgeSummary, compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
 import type {
-  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeClaim, KnowledgeEpisodeDecision,
+  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeCategory, KnowledgeClaim, KnowledgeEpisodeDecision,
   KnowledgeEvidence, KnowledgeManifest, KnowledgeReviewCursor, KnowledgeReviewTask, KnowledgeScope,
   KnowledgeSkipReason, KnowledgeSnapshot, KnowledgeTrack,
   PersistKnowledgeResult,
@@ -22,6 +22,9 @@ const SAFE_GENERATION_RE = /^[0-9TZ-]+-[a-f0-9]{12}$/u;
 const PROJECT_SCOPE_RE = /^project:[a-f0-9]{16}$/u;
 const UNVERIFIED_CLAIM_RE = /(?:待验证|尚未(?:验证|确认)|未经(?:验证|确认)|未(?:经)?证实|推测|猜测|疑似|可能是|可能由于|可能导致|或许|unverified|unconfirmed|speculat(?:e|ive|ion)|hypothes(?:is|ize)|suspect(?:ed|ion)?|possibly|probably)/iu;
 const VOLATILE_ARGUMENT_RE = /--(?:namespace|name|server_name|security_group_id|subnet_id|vpc_id|image_id|project_id)(?:\.\d+)?=(?!<[^>]+>|\$?\{)[^\s`"']+/iu;
+const KNOWLEDGE_CATEGORIES = new Set<KnowledgeCategory>([
+  "principle", "configuration", "method", "strategy", "caution",
+]);
 
 export class KnowledgeCommitBusyError extends Error {}
 
@@ -248,6 +251,9 @@ function normalizeCandidate(
   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 { reason: "invalid-schema" };
+  if (typeof raw.category !== "string" || !KNOWLEDGE_CATEGORIES.has(raw.category as KnowledgeCategory)) {
+    return { reason: "invalid-schema" };
+  }
   if (raw.durability !== "stable") return { reason: "unstable" };
   if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence) return { reason: "low-confidence" };
   if (raw.targetId !== undefined && raw.targetId !== null
@@ -301,6 +307,7 @@ function normalizeCandidate(
     || raw.action === "retire" ? raw.action : "add";
   return { candidate: {
     key: compactKnowledgeText(raw.key, 160),
+    category: raw.category as KnowledgeCategory,
     identityKey: typeof raw.identityKey === "string" ? compactKnowledgeText(raw.identityKey, 240).toLowerCase() : undefined,
     targetId,
     title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
@@ -330,7 +337,8 @@ function writeRejectedPending(directory: string, reason: KnowledgeSkipReason, va
 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.title}`, "", candidate.summary, "", `Category: ${candidate.category}`,
+    `Keywords: ${candidate.keywords.join(", ")}`, "",
     candidate.body, "", "## Evidence", "", ...candidate.evidence.map((item) => `- ${item}`), "",
   ].join("\n");
 }
@@ -359,7 +367,8 @@ function generateMemory(catalog: KnowledgeCatalog, projectKey?: string): string
     .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}`;
+    const category = item.category ? `${item.category}; ` : "";
+    const line = `- [${item.id}] (${category}${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;
@@ -509,6 +518,7 @@ export function commitKnowledgeReview(
           continue;
         }
         existing.evidenceCount += candidate.evidence.length;
+        existing.category ??= candidate.category;
         existing.updatedAt = new Date().toISOString();
         result.updated++;
         continue;
@@ -552,6 +562,7 @@ export function commitKnowledgeReview(
         existing.contentHash = createHash("sha256").update(content).digest("hex");
         existing.keywords = [...new Set([...existing.keywords, ...candidate.keywords])].slice(0, STORAGE.maxKeywordCount);
         existing.claimKeys = [...new Set([...(existing.claimKeys ?? []), ...newClaimKeys])];
+        existing.category ??= candidate.category;
         existing.evidenceCount += candidate.evidence.length;
         existing.updatedAt = new Date().toISOString();
         result.updated++;
@@ -584,7 +595,8 @@ export function commitKnowledgeReview(
       const entry: KnowledgeCatalogEntry = {
         id, fingerprint: existing?.fingerprint ?? fingerprint, contentHash: hash,
         title: candidate.title, summary: candidate.summary,
-        keywords: candidate.keywords, scope: existing?.scope ?? candidate.scope, track, file: relativeFile,
+        keywords: candidate.keywords, category: candidate.category,
+        scope: existing?.scope ?? candidate.scope, track, file: relativeFile,
         evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
         identityKey: candidate.identityKey ?? existing?.identityKey,
         claimKeys: candidate.claims?.map((claim) => claim.key) ?? existing?.claimKeys,

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

@@ -1,4 +1,5 @@
 export type KnowledgeTrack = "rule" | "topic";
+export type KnowledgeCategory = "principle" | "configuration" | "method" | "strategy" | "caution";
 export type KnowledgeScope = "global" | `project:${string}`;
 export type KnowledgeAction = "add" | "reinforce" | "extend" | "correct" | "retire";
 export type KnowledgeDurability = "stable";
@@ -50,6 +51,7 @@ export interface KnowledgeEpisodeDecision {
 
 export interface KnowledgeCandidate {
   key: string;
+  category: KnowledgeCategory;
   identityKey?: string;
   targetId?: string;
   title: string;
@@ -75,6 +77,7 @@ export interface KnowledgeCatalogEntry {
   title: string;
   summary: string;
   keywords: string[];
+  category?: KnowledgeCategory;
   scope: KnowledgeScope;
   track: KnowledgeTrack;
   file: string;

package/.pi/lib/models/sse-response.ts

@@ -0,0 +1,50 @@
+const SSE_CONTENT_TYPE = "text/event-stream";
+const DONE_EVENT_RE = /(?:^|\r?\n)data:\s*\[DONE\]\s*(?:\r?\n|$)/u;
+const MARKER_TAIL_CHARS = 64;
+
+function closeAtDone(response: Response): Response {
+  if (!response.body || !response.headers.get("content-type")?.toLowerCase().includes(SSE_CONTENT_TYPE)) {
+    return response;
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let tail = "";
+  let closed = false;
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const chunk = await reader.read();
+        if (chunk.done) {
+          closed = true;
+          controller.close();
+          return;
+        }
+        controller.enqueue(chunk.value);
+        const text = `${tail}${decoder.decode(chunk.value, { stream: true })}`;
+        tail = text.slice(-MARKER_TAIL_CHARS);
+        if (!DONE_EVENT_RE.test(text)) return;
+        closed = true;
+        controller.close();
+        void reader.cancel("OpenAI SSE completed with [DONE]").catch(() => {});
+      } catch (error) {
+        closed = true;
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      if (closed) return;
+      closed = true;
+      return reader.cancel(reason);
+    },
+  });
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+export function closeOpenAiSseAtDone(fetchImplementation: typeof fetch = globalThis.fetch): typeof fetch {
+  return (async (input, init) => closeAtDone(await fetchImplementation(input, init))) as typeof fetch;
+}

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

@@ -44,7 +44,7 @@ export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
     maxExistingContextItems: 8,
     maxExistingBodyItems: 2,
     maxExistingBodyChars: 600,
-    maxCandidates: 3,
+    maxCandidates: 2,
     minimumConfidence: 0.72,
   }),
   storage: Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadooppei/hwcode",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "description": "A customizable terminal coding agent with local-model support and HWCode workflows.",
   "type": "module",
   "bin": {