@hasna/hook-knowledge-context 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# hook-knowledge-context
+
+Codewith lifecycle hook that injects deterministic Knowledge context packs.
+
+## Installation
+
+```bash
+hooks install knowledge-context --target codewith
+```
+
+By default this prints a Codewith TOML fragment and does not mutate managed
+Codewith config. Apply that fragment through `open-configs` or the managed
+config renderer. For explicit local testing only:
+
+```bash
+hooks install knowledge-context --target codewith --apply-codewith --codewith-config /tmp/codewith-config.toml
+```
+
+## How it works
+
+On `SessionStart`, `UserPromptSubmit`, and `SubagentStart`, the hook builds a
+small redacted query from the hook input and runs:
+
+```bash
+knowledge context pack <query> --from search --max-items <n> --max-tokens <n> --json
+```
+
+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.
+
+All failures are fail-open: missing CLI, timeout, nonzero exit, malformed JSON,
+bad stdin, or empty packs return `{"continue":true}` without context.
+
+## Configuration
+
+```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_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
+export HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS=8000
+```
+
+## Events
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `SubagentStart`

package/dist/hook.d.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+/**
+ * Codewith Hook: knowledge-context
+ *
+ * Deterministically injects bounded Knowledge context into Codewith lifecycle
+ * events. This hook never calls LLM providers, semantic search, web search, or
+ * raw stores directly; it delegates to `knowledge context pack --from search`.
+ */
+export type KnowledgeContextEvent = "SessionStart" | "UserPromptSubmit" | "SubagentStart";
+interface HookInput {
+    session_id?: string;
+    cwd?: string;
+    hook_event_name?: string;
+    model?: string;
+    permission_mode?: string;
+    source?: string;
+    prompt?: string;
+    user_prompt?: string;
+    agent_id?: string;
+    agent_type?: string;
+    turn_id?: string;
+}
+interface HookOutput {
+    continue: boolean;
+    hookSpecificOutput?: {
+        hookEventName: KnowledgeContextEvent;
+        additionalContext: string;
+    };
+}
+export interface KnowledgeContextConfig {
+    command: string;
+    timeoutMs: number;
+    maxItems: number;
+    maxTokens: number;
+    maxQueryChars: number;
+    maxOutputChars: number;
+}
+export interface KnowledgeExecResult {
+    ok: boolean;
+    stdout?: string;
+    timedOut?: boolean;
+}
+export type KnowledgeExecutor = (query: string, config: KnowledgeContextConfig) => Promise<KnowledgeExecResult>;
+export declare function getConfig(env?: NodeJS.ProcessEnv): KnowledgeContextConfig;
+export declare function isKnowledgeContextEvent(value: string | undefined): value is KnowledgeContextEvent;
+export declare function redactSecrets(text: string): string;
+export declare function sanitizeQuery(text: string, maxChars: number): string;
+export declare function buildQuery(input: HookInput, config: KnowledgeContextConfig): string | null;
+export declare function buildKnowledgeArgs(query: string, config: KnowledgeContextConfig): string[];
+export declare function spawnKnowledgeContextPack(query: string, config: KnowledgeContextConfig): Promise<KnowledgeExecResult>;
+export declare function truncate(text: string, max: number): string;
+export declare function extractContextText(pack: unknown): string | null;
+export declare function formatAdditionalContext(event: KnowledgeContextEvent, context: string, config: KnowledgeContextConfig): string;
+export declare function buildHookOutput(input: HookInput | null, executor?: KnowledgeExecutor, env?: NodeJS.ProcessEnv): Promise<HookOutput>;
+export declare function run(): Promise<void>;
+export {};

package/dist/hook.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/hook.ts
+import { readFileSync } from "fs";
+import { spawn } from "child_process";
+var DEFAULT_TIMEOUT_MS = 1500;
+var DEFAULT_MAX_ITEMS = 6;
+var DEFAULT_MAX_TOKENS = 1200;
+var DEFAULT_MAX_QUERY_CHARS = 1200;
+var DEFAULT_MAX_OUTPUT_CHARS = 8000;
+var SUPPORTED_EVENTS = new Set([
+  "SessionStart",
+  "UserPromptSubmit",
+  "SubagentStart"
+]);
+function readStdinJson() {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input)
+      return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+function respond(output) {
+  console.log(JSON.stringify(output));
+}
+function boundedNumber(raw, fallback, min, max) {
+  const value = Number(raw);
+  if (!Number.isFinite(value))
+    return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+function commandFromEnv(raw) {
+  if (raw && /^[^\s\0]+$/.test(raw))
+    return raw;
+  return "knowledge";
+}
+function getConfig(env = process.env) {
+  return {
+    command: commandFromEnv(env.HOOKS_KNOWLEDGE_COMMAND),
+    timeoutMs: boundedNumber(env.HOOKS_KNOWLEDGE_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100, 1e4),
+    maxItems: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_ITEMS, DEFAULT_MAX_ITEMS, 1, 20),
+    maxTokens: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_TOKENS, DEFAULT_MAX_TOKENS, 100, 8000),
+    maxQueryChars: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_QUERY_CHARS, DEFAULT_MAX_QUERY_CHARS, 80, 4000),
+    maxOutputChars: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS, DEFAULT_MAX_OUTPUT_CHARS, 500, 20000)
+  };
+}
+function isKnowledgeContextEvent(value) {
+  return SUPPORTED_EVENTS.has(value);
+}
+function stringField(input, key) {
+  const value = input[key];
+  return typeof value === "string" ? value : "";
+}
+function redactSecrets(text) {
+  let redacted = text;
+  redacted = redacted.replace(/\b(api[_-]?key|token|secret|password|passwd|pwd)\b\s*[:=]\s*[^,\s]+/gi, (_match, key) => `${key}=<redacted>`);
+  redacted = redacted.replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bxox[baprs]-[A-Za-z0-9-]{20,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bAKIA[0-9A-Z]{16}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bAIza[0-9A-Za-z_-]{20,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\b[A-Za-z0-9+/]{48,}={0,2}\b/g, "<redacted>");
+  return redacted;
+}
+function sanitizeQuery(text, maxChars) {
+  const normalized = text.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  const redacted = redactSecrets(normalized);
+  return redacted.length > maxChars ? redacted.slice(0, maxChars).trim() : redacted;
+}
+function buildQuery(input, config) {
+  const cwd = stringField(input, "cwd");
+  const event = stringField(input, "hook_event_name");
+  if (event === "UserPromptSubmit") {
+    const prompt = stringField(input, "prompt") || stringField(input, "user_prompt");
+    return sanitizeQuery(`Codewith user prompt context. cwd: ${cwd}. prompt: ${prompt}`, config.maxQueryChars);
+  }
+  if (event === "SubagentStart") {
+    const agentType = stringField(input, "agent_type") || "subagent";
+    const turnId = stringField(input, "turn_id");
+    return sanitizeQuery(`Codewith subagent start context. cwd: ${cwd}. agent type: ${agentType}. turn: ${turnId}`, config.maxQueryChars);
+  }
+  if (event === "SessionStart") {
+    const source = stringField(input, "source") || "startup";
+    const model = stringField(input, "model");
+    return sanitizeQuery(`Codewith session start context. cwd: ${cwd}. source: ${source}. model: ${model}`, config.maxQueryChars);
+  }
+  return null;
+}
+function buildKnowledgeArgs(query, config) {
+  return [
+    "context",
+    "pack",
+    query,
+    "--from",
+    "search",
+    "--max-items",
+    String(config.maxItems),
+    "--max-tokens",
+    String(config.maxTokens),
+    "--json"
+  ];
+}
+function spawnKnowledgeContextPack(query, config) {
+  const args = buildKnowledgeArgs(query, config);
+  return new Promise((resolve) => {
+    let stdout = "";
+    let settled = false;
+    let timedOut = false;
+    let timer;
+    const settle = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      if (timer)
+        clearTimeout(timer);
+      resolve(result);
+    };
+    const child = spawn(config.command, args, {
+      stdio: ["ignore", "pipe", "ignore"],
+      env: process.env
+    });
+    timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill("SIGTERM");
+      } catch {}
+    }, config.timeoutMs);
+    child.stdout.setEncoding("utf-8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      if (stdout.length > config.maxOutputChars * 2) {
+        stdout = stdout.slice(0, config.maxOutputChars * 2);
+      }
+    });
+    child.on("error", () => settle({ ok: false, timedOut }));
+    child.on("close", (code) => settle({ ok: code === 0 && !timedOut, stdout, timedOut }));
+  });
+}
+function firstString(obj, keys) {
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === "string" && value.trim())
+      return value.trim();
+  }
+  return null;
+}
+function firstArray(obj, keys) {
+  for (const key of keys) {
+    const value = obj[key];
+    if (Array.isArray(value))
+      return value;
+  }
+  return null;
+}
+function truncate(text, max) {
+  if (text.length <= max)
+    return text;
+  if (max <= 3)
+    return text.slice(0, max);
+  return `${text.slice(0, max - 3)}...`;
+}
+function formatPackItems(items) {
+  const lines = [];
+  for (const [index, item] of items.entries()) {
+    if (typeof item === "string" && item.trim()) {
+      lines.push(`- ${truncate(item.trim(), 900)}`);
+      continue;
+    }
+    if (!item || typeof item !== "object")
+      continue;
+    const obj = item;
+    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"]);
+    if (!body && !source)
+      continue;
+    const suffix = source ? ` (source: ${truncate(source, 180)})` : "";
+    lines.push(`- ${truncate(title, 160)}${suffix}${body ? `: ${truncate(body, 900)}` : ""}`);
+  }
+  return lines.length > 0 ? lines.join(`
+`) : null;
+}
+function extractContextText(pack) {
+  if (typeof pack === "string") {
+    return pack.trim() || null;
+  }
+  if (Array.isArray(pack)) {
+    return formatPackItems(pack);
+  }
+  if (!pack || typeof pack !== "object") {
+    return null;
+  }
+  const obj = pack;
+  const direct = firstString(obj, ["additionalContext", "context", "markdown", "content", "text", "summary"]);
+  if (direct)
+    return direct;
+  for (const key of ["pack", "contextPack", "context_pack", "data", "result"]) {
+    const nested = obj[key];
+    const text = extractContextText(nested);
+    if (text)
+      return text;
+  }
+  const items = firstArray(obj, ["items", "results", "sources", "citations"]);
+  return items ? formatPackItems(items) : null;
+}
+function formatAdditionalContext(event, context, config) {
+  const header = `[hook-knowledge-context] Deterministic Knowledge context (${event}; knowledge context pack --from search):`;
+  const safeContext = redactSecrets(context.trim());
+  return `${header}
+
+${truncate(safeContext, Math.max(0, config.maxOutputChars - header.length - 2))}`;
+}
+async function buildHookOutput(input, executor = spawnKnowledgeContextPack, env = process.env) {
+  if (env.HOOKS_KNOWLEDGE_CONTEXT_DISABLE === "1") {
+    return { continue: true };
+  }
+  if (!input) {
+    return { continue: true };
+  }
+  const event = input.hook_event_name;
+  if (!isKnowledgeContextEvent(event)) {
+    return { continue: true };
+  }
+  const config = getConfig(env);
+  const query = buildQuery(input, config);
+  if (!query) {
+    return { continue: true };
+  }
+  try {
+    const result = await executor(query, config);
+    if (!result.ok || !result.stdout) {
+      return { continue: true };
+    }
+    const parsed = JSON.parse(result.stdout);
+    const context = extractContextText(parsed);
+    if (!context) {
+      return { continue: true };
+    }
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: event,
+        additionalContext: formatAdditionalContext(event, context, config)
+      }
+    };
+  } catch {
+    return { continue: true };
+  }
+}
+async function run() {
+  respond(await buildHookOutput(readStdinJson()));
+}
+if (__require.main == __require.module) {
+  run();
+}
+export {
+  truncate,
+  spawnKnowledgeContextPack,
+  sanitizeQuery,
+  run,
+  redactSecrets,
+  isKnowledgeContextEvent,
+  getConfig,
+  formatAdditionalContext,
+  extractContextText,
+  buildQuery,
+  buildKnowledgeArgs,
+  buildHookOutput
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/hook-knowledge-context",
+  "version": "0.1.0",
+  "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
+  "type": "module",
+  "main": "./dist/hook.js",
+  "exports": {
+    ".": {
+      "import": "./dist/hook.js",
+      "types": "./dist/hook.d.ts"
+    }
+  },
+  "files": [
+    "dist/hook.js",
+    "dist/hook.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/hook.ts --outdir ./dist --target node && tsc -p tsconfig.json --emitDeclarationOnly --declaration --declarationMap false --noEmit false",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "codewith",
+    "hook",
+    "knowledge",
+    "context",
+    "deterministic",
+    "session-start",
+    "user-prompt-submit",
+    "subagent-start"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasna/hooks.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "@types/node": "^20",
+    "typescript": "^5.0.0"
+  }
+}