@hasna/hooks 0.3.1 → 0.3.3

package/bin/index.js

@@ -2089,7 +2089,7 @@ var init_registry = __esm(() => {
       name: "knowledge-context",
       displayName: "Knowledge Context",
       description: "Injects deterministic Knowledge context packs into Codewith SessionStart, UserPromptSubmit, and SubagentStart",
-      version: "0.1.0",
+      version: "0.1.2",
       category: "Context Management",
       event: "SessionStart",
       events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],
@@ -4126,7 +4126,7 @@ function codewithMatcher(matcher) {
 function codewithTimeout(name) {
   switch (name) {
     case "knowledge-context":
-      return 2;
+      return 6;
     case "session-start":
       return 8;
     case "pre-bash":

package/dist/index.js

@@ -1010,7 +1010,7 @@ var HOOKS = [
     name: "knowledge-context",
     displayName: "Knowledge Context",
     description: "Injects deterministic Knowledge context packs into Codewith SessionStart, UserPromptSubmit, and SubagentStart",
-    version: "0.1.0",
+    version: "0.1.2",
     category: "Context Management",
     event: "SessionStart",
     events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],
@@ -1452,7 +1452,7 @@ function codewithMatcher(matcher) {
 function codewithTimeout(name) {
   switch (name) {
     case "knowledge-context":
-      return 2;
+      return 6;
     case "session-start":
       return 8;
     case "pre-bash":

package/hooks/hook-knowledge-context/README.md

@@ -29,7 +29,10 @@ The hook intentionally does not pass `--semantic`, does not call web search,
 does not call ask/build/generate flows, and does not crawl raw stores directly.
 When Knowledge returns a nonempty context pack, the hook redacts credential-like
 text from that pack and emits Codewith-native
-`hookSpecificOutput.additionalContext` with the same event name.
+`hookSpecificOutput.additionalContext` with the same event name. Citation-only
+packs are expanded into progressive context lines with a bounded preview and a
+`knowledge get --id ... --json` read hint so agents can decide which full items
+are worth opening.
 
 All failures are fail-open: missing CLI, timeout, nonzero exit, malformed JSON,
 bad stdin, or empty packs return `{"continue":true}` without context.
@@ -39,7 +42,7 @@ bad stdin, or empty packs return `{"continue":true}` without context.
 ```bash
 export HOOKS_KNOWLEDGE_CONTEXT_DISABLE=1    # Kill switch
 export HOOKS_KNOWLEDGE_COMMAND=knowledge    # CLI command/path
-export HOOKS_KNOWLEDGE_TIMEOUT_MS=1500      # Per-call timeout
+export HOOKS_KNOWLEDGE_TIMEOUT_MS=5000      # Per-call timeout
 export HOOKS_KNOWLEDGE_MAX_ITEMS=6          # Context pack item budget
 export HOOKS_KNOWLEDGE_MAX_TOKENS=1200      # Context pack token budget
 export HOOKS_KNOWLEDGE_MAX_QUERY_CHARS=1200 # Redacted query bound

package/hooks/hook-knowledge-context/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hook-knowledge-context",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
   "type": "module",
   "main": "./dist/hook.js",

package/hooks/hook-knowledge-context/src/hook.test.ts

@@ -13,7 +13,7 @@ import {
 
 const baseConfig: KnowledgeContextConfig = {
   command: "knowledge",
-  timeoutMs: 1500,
+  timeoutMs: 5000,
   maxItems: 6,
   maxTokens: 1200,
   maxQueryChars: 1200,
@@ -21,6 +21,11 @@ const baseConfig: KnowledgeContextConfig = {
 };
 
 describe("hook-knowledge-context", () => {
+  test("defaults Knowledge CLI timeout to 5000ms and keeps env override", () => {
+    expect(getConfig({}).timeoutMs).toBe(5000);
+    expect(getConfig({ HOOKS_KNOWLEDGE_TIMEOUT_MS: "2345" }).timeoutMs).toBe(2345);
+  });
+
   test("builds deterministic knowledge context pack args without semantic, web, or generation flags", () => {
     const args = buildKnowledgeArgs("repo hook context", baseConfig);
 
@@ -165,4 +170,21 @@ describe("hook-knowledge-context", () => {
     expect(extractContextText({ pack: { context: "direct context" } })).toBe("direct context");
     expect(extractContextText([{ title: "One", text: "Body", uri: "knowledge://item/one" }])).toContain("Body");
   });
+
+  test("formats citation previews as useful progressive blurbs with read commands", () => {
+    const text = extractContextText({
+      citations: [
+        {
+          id: "cite_123",
+          source_ref: "knowledge://item/k_example",
+          quote_preview: "A short preview that tells the agent why this Knowledge item might matter.",
+        },
+      ],
+    });
+
+    expect(text).toContain("Knowledge item k_example");
+    expect(text).toContain("cite_123");
+    expect(text).toContain("A short preview");
+    expect(text).toContain("read: knowledge get --id k_example --json");
+  });
 });

package/hooks/hook-knowledge-context/src/hook.ts

@@ -55,7 +55,7 @@ export type KnowledgeExecutor = (
   config: KnowledgeContextConfig
 ) => Promise<KnowledgeExecResult>;
 
-const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_MAX_ITEMS = 6;
 const DEFAULT_MAX_TOKENS = 1200;
 const DEFAULT_MAX_QUERY_CHARS = 1200;
@@ -227,6 +227,18 @@ function firstString(obj: Record<string, unknown>, keys: string[]): string | nul
   return null;
 }
 
+function firstSourceString(obj: Record<string, unknown>): string | null {
+  const direct = firstString(obj, ["source_ref", "source_uri", "source", "uri", "ref", "url", "citation"]);
+  if (direct) return direct;
+
+  const source = obj.source;
+  if (source && typeof source === "object") {
+    return firstString(source as Record<string, unknown>, ["uri", "ref", "url", "id"]);
+  }
+
+  return null;
+}
+
 function firstArray(obj: Record<string, unknown>, keys: string[]): unknown[] | null {
   for (const key of keys) {
     const value = obj[key];
@@ -241,6 +253,15 @@ export function truncate(text: string, max: number): string {
   return `${text.slice(0, max - 3)}...`;
 }
 
+function compactText(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function knowledgeItemId(source: string | null): string | null {
+  const match = source?.match(/^knowledge:\/\/item\/([^/?#\s]+)$/);
+  return match?.[1] ?? null;
+}
+
 function formatPackItems(items: unknown[]): string | null {
   const lines: string[] = [];
 
@@ -252,12 +273,35 @@ function formatPackItems(items: unknown[]): string | null {
     if (!item || typeof item !== "object") continue;
 
     const obj = item as Record<string, unknown>;
-    const title = firstString(obj, ["title", "name", "id", "ref", "uri"]) || `item ${index + 1}`;
-    const body = firstString(obj, ["summary", "text", "content", "snippet", "preview", "body"]);
-    const source = firstString(obj, ["source", "uri", "ref", "url", "citation"]);
+    const citationId = firstString(obj, ["id", "citation_id", "citationId"]);
+    const source = firstSourceString(obj);
+    const itemId = knowledgeItemId(source);
+    const title =
+      firstString(obj, ["title", "name"]) ||
+      (itemId ? `Knowledge item ${itemId}` : citationId || `item ${index + 1}`);
+    const body = firstString(obj, [
+      "summary",
+      "text",
+      "content",
+      "snippet",
+      "preview",
+      "quote_preview",
+      "quotePreview",
+      "excerpt",
+      "body",
+      "description",
+    ]);
     if (!body && !source) continue;
-    const suffix = source ? ` (source: ${truncate(source, 180)})` : "";
-    lines.push(`- ${truncate(title, 160)}${suffix}${body ? `: ${truncate(body, 900)}` : ""}`);
+
+    const suffixParts = [
+      citationId && citationId !== title ? citationId : null,
+      source ? `source: ${truncate(source, 180)}` : null,
+    ].filter(Boolean);
+    const suffix = suffixParts.length > 0 ? ` (${suffixParts.join("; ")})` : "";
+    lines.push(`- ${truncate(title, 160)}${suffix}${body ? `: ${truncate(compactText(body), 520)}` : ""}`);
+    if (itemId) {
+      lines.push(`  read: knowledge get --id ${itemId} --json`);
+    }
   }
 
   return lines.length > 0 ? lines.join("\n") : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {