@drdeeks/character-kit 1.0.1

package/node/examples/.agent/habits/verify-against-docs.yaml

@@ -0,0 +1,15 @@
+# Habit: verify-against-docs
+# Source question: "Did I verify my work against actual documentation when it was available?"
+# Correct action: when real docs/source exist, verify against THEM, not against memory or README prose.
+# Evidence: claims trace to the actual API/doc/source I read; where docs conflict with prose, docs win.
+# Logic: docs are the contract the system actually honors; prose summarizing them drifts. You know it's
+#        right because it matches the authority, not a secondhand description.
+name: "verify_against_docs"
+prompt: "Did I verify against the actual docs when available?"
+enforcement:
+  level: "reminder"
+behavior:
+  kind: "standard"
+  assert: "When real docs/source exist, verify against THEM, not memory or README prose."
+  evidence: "Claims trace to the actual API/doc/source I read; where docs conflict with prose, docs win."
+  logic: "Docs are the contract the system honors; prose summarizing them drifts. Right = matches the authority, not a description."

package/node/examples/.agent/habits/verify-functionality-not-syntax.yaml

@@ -0,0 +1,15 @@
+# Habit: verify-functionality-not-syntax
+# Correct action: verify functionality, not just syntax. A syntax pass is never 'done'.
+# Evidence: ran the code / exercised the path; observed expected behavior. A green linter alone is
+#           not evidence of function.
+# Logic: a thing that parses can still be wrong. Functional proof requires execution, not compilation.
+#        You know it works because you watched it work, not because it compiled.
+name: "verify_functionality_not_syntax"
+prompt: "Did I verify this 100% by testing functionality, not just a syntax pass?"
+enforcement:
+  level: "reminder"
+behavior:
+  kind: "standard"
+  assert: "Verify functionality, not just syntax. A syntax pass is never 'done'."
+  evidence: "Ran the code / exercised the path; observed expected behavior. A green linter alone is not evidence of function."
+  logic: "A thing that parses can still be wrong. Functional proof requires execution, not compilation."

package/node/examples/.agent/habits/versioning-discipline.yaml

@@ -0,0 +1,18 @@
+# Habit: versioning-discipline
+# Source question: "Is the version accurate, present, and self-identifying?"
+# Correct action: stamp a VERSION file and an AIK_VERSION (or equivalent) constant so the
+#               artifact identifies its own version; bump it on every meaningful change;
+#               never ship a dir that can't state what it is.
+# Evidence: a VERSION file exists at repo root, the runtime constant matches it, and the
+#           two are updated together whenever behavior changes.
+# Logic: an artifact that can't name its own version can't be debugged, diffed, or trusted.
+#        Self-identifying = the dir tells you what it is without external context.
+name: "versioning_discipline"
+prompt: "Is the version stamped, matching, and bumped on change?"
+enforcement:
+  level: "reminder"
+behavior:
+  kind: "standard"
+  assert: "Stamp VERSION file + runtime version constant; they match; bump both on any meaningful change."
+  evidence: "VERSION file at repo root; runtime constant equals it; both updated together when behavior changes."
+  logic: "An artifact that can't name its own version can't be debugged or trusted. Self-identifying is non-negotiable."

package/node/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@character-kit/agent-character-kit",
+  "version": "1.0.0",
+  "description": "Universal agent character enforcement, knowledge indexing, and memory with YAML frontmatter. True plugin: install once, reference as @character-kit in any harness config.",
+  "main": "src/index.js",
+  "bin": {
+    "ack": "node/bin/ack.js",
+    "character-kit": "node/bin/ack.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "start": "node bin/aik.js",
+    "install": "node node/bin/install.js",
+    "ack-install": "node node/bin/install.js"
+  },
+  "keywords": [
+    "agent",
+    "character",
+    "agent-character",
+    "enforcement",
+    "knowledge",
+    "memory",
+    "semantic-search",
+    "hooks",
+    "yaml",
+    "frontmatter",
+    "claude",
+    "cursor",
+    "gemini",
+    "hermes",
+    "opencode"
+  ],
+  "author": "drdeeks",
+  "license": "MIT",
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.0",
+    "glob": "^10.3.0",
+    "commander": "^11.1.0"
+  },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "overrides": {
+    "onnxruntime-web": "^1.27.0",
+    "onnx-proto": "^8.0.1",
+    "protobufjs": "^7.2.4"
+  }
+}

package/node/src/enforcer/client.js

@@ -0,0 +1,149 @@
+import net from "net";
+import fs from "fs";
+import path from "path";
+
+// Socket default MUST match the daemon (agent_enforcer_daemon.js): it lives
+// under AGENT_WORKSPACE/.agent/enforcer.sock so the kit is portable (no /run).
+// Override with ENFORCER_SOCKET if your deployment differs.
+const DEFAULT_SOCKET = process.env.AGENT_WORKSPACE
+  ? path.join(process.env.AGENT_WORKSPACE, ".agent", "enforcer.sock")
+  : path.join(process.env.HOME || "/root", ".agent-character-kit", "workspace", ".agent", "enforcer.sock");
+
+const SOCKET_PATH = process.env.ENFORCER_SOCKET || DEFAULT_SOCKET;
+
+/**
+ * Enforcer Client — RPC to the character enforcer daemon.
+ *
+ * The enforcer daemon runs as a separate systemd service.
+ * The agent CANNOT modify, patch, or kill it.
+ * All tool calls go through here for validation.
+ */
+export class EnforcerClient {
+  constructor(socketPath) {
+    this.socketPath = socketPath || SOCKET_PATH;
+  }
+
+  /**
+   * Send RPC request to enforcer daemon.
+   * @param {string} method - RPC method name
+   * @param {object} params - Method parameters
+   * @returns {Promise<object>} - Response from enforcer
+   */
+  async call(method, params = {}) {
+    return new Promise((resolve, reject) => {
+      if (!fs.existsSync(this.socketPath)) {
+        resolve({ error: "enforcer socket not found", denied: false });
+        return;
+      }
+
+      let retried = false;
+      const doCall = () => {
+        const socket = net.createConnection(this.socketPath);
+        const request = JSON.stringify({ method, params }) + "\n";
+        let data = "";
+
+        const timeout = setTimeout(() => {
+          socket.destroy();
+          resolve({ error: "enforcer timeout", denied: false });
+        }, 5000);
+
+        socket.on("connect", () => {
+          socket.write(request);
+        });
+
+        socket.on("data", (chunk) => {
+          data += chunk.toString();
+          if (data.includes("\n")) {
+            clearTimeout(timeout);
+            socket.destroy();
+            try {
+              const parsed = JSON.parse(data.trim());
+              // Retry once on "invalid request" (first-request buffering issue)
+              if (parsed.error === "invalid request" && !retried) {
+                retried = true;
+                console.error("[EnforcerClient] Retrying after invalid request...");
+                setTimeout(doCall, 10);
+                return;
+              }
+              resolve(parsed);
+            } catch (e) {
+              resolve({ error: "invalid response", denied: false });
+            }
+          }
+        });
+
+        socket.on("error", (err) => {
+          clearTimeout(timeout);
+          resolve({ error: err.message, denied: false });
+        });
+
+        socket.on("timeout", () => {
+          clearTimeout(timeout);
+          socket.destroy();
+          resolve({ error: "socket timeout", denied: false });
+        });
+      };
+      doCall();
+    });
+  }
+
+  /**
+   * Validate a tool call through the enforcer.
+   * @param {string} tool - Tool name
+   * @param {object} params - Tool parameters
+   * @param {string} characterHash - Agent character hash
+   * @returns {Promise<{allowed: boolean, reason?: string, reflection?: string}>}
+   */
+  async validateTool(tool, params, characterHash = "unknown") {
+    // The daemon's socket contract is FLAT: { method:"execute_tool",
+    // params:{ tool, command, character_hash } }. executeTool(tool, params)
+    // reads params.command via _extractCommand. Do NOT nest params inside
+    // params — that was the bug that made every call pass (command resolved
+    // to the tool name instead of the real command).
+    const command =
+      (params && (params.command || params.cmd || params.code)) || "";
+    const response = await this.call("execute_tool", {
+      tool,
+      command,
+      character_hash: characterHash,
+    });
+
+    // Enforcer unreachable → fail closed by default (see processToolCall).
+    if (response.error) {
+      return {
+        allowed: false,
+        error: true,
+        reason: `Enforcer unavailable: ${response.error}`,
+        reflection:
+          "The enforcer could not be reached. character cannot be verified, " +
+          "so the action is blocked. A guard that fails open is no guard.",
+      };
+    }
+
+    if (response.denied) {
+      return {
+        allowed: false,
+        reason: response.reason || "Denied by enforcer",
+        reflection: response.reflection || "",
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * Send heartbeat to enforcer.
+   */
+  async heartbeat(status = "ok") {
+    return this.call("heartbeat", { status });
+  }
+
+  /**
+   * Validate workspace integrity.
+   */
+  async validateWorkspace() {
+    return this.call("validate_workspace");
+  }
+}
+
+export default new EnforcerClient();

package/node/src/hooks/character.js

@@ -0,0 +1,286 @@
+import { EnforcerClient } from "../enforcer/client.js";
+import fs from "fs";
+import path from "path";
+
+const AUDIT_DIR = path.join(
+  process.env.HOME || "/root",
+  "var", "log", "agent-enforcer"
+);
+const AUDIT_LOG = path.join(AUDIT_DIR, "tool-audit.jsonl");
+
+/**
+ * Character Hook — Core enforcement for all tool calls.
+ *
+ * This is the gatekeeper. Every tool call from any framework
+ * goes through here before execution.
+ *
+ * Flow:
+ *   1. Receive tool call (framework-specific format)
+ *   2. Normalize to unified format
+ *   3. Validate through enforcer daemon
+ *   4. Return allow/deny in framework-native format
+ *   5. Log to audit trail
+ */
+
+// ─── Framework Detection ────────────────────────────────────────────────────
+
+function detectFramework(payload) {
+  if (payload.hook_event_name) {
+    const evt = payload.hook_event_name;
+    if (["PreToolUse", "PostToolUse", "SessionStart", "Stop"].includes(evt)) return "claude";
+    if (["BeforeTool", "AfterTool", "BeforeToolSelection"].includes(evt)) return "gemini";
+    if (["preToolUse", "postToolUse", "beforeShellExecution"].includes(evt)) return "cursor";
+  }
+  if (payload.tool_name && payload.args) return "hermes";
+  if (payload.tool && payload.args) return "opencode";
+  return "generic";
+}
+
+// ─── Normalization ──────────────────────────────────────────────────────────
+
+function normalizeInput(payload, framework) {
+  switch (framework) {
+    case "claude":
+      return {
+        tool: payload.tool_name || "unknown",
+        params: payload.tool_input || {},
+        event: (payload.hook_event_name || "PreToolUse").toLowerCase(),
+        sessionId: payload.session_id,
+        cwd: payload.cwd,
+      };
+    case "cursor":
+      return {
+        tool: payload.tool_name || payload.tool || "unknown",
+        params: payload.tool_input || payload.args || {},
+        event: (payload.hook_event_name || "preToolUse").toLowerCase(),
+        sessionId: payload.session_id,
+        cwd: payload.cwd,
+      };
+    case "gemini":
+      return {
+        tool: payload.tool_name || "unknown",
+        params: payload.tool_input || {},
+        event: (payload.hook_event_name || "BeforeTool").toLowerCase(),
+        sessionId: payload.session_id,
+        cwd: payload.cwd,
+      };
+    case "hermes":
+      return {
+        tool: payload.tool_name || "unknown",
+        params: payload.args || {},
+        event: "pre_tool_call",
+        sessionId: payload.task_id,
+      };
+    case "opencode":
+      return {
+        tool: payload.tool || payload.tool_name || "unknown",
+        params: payload.args || payload.tool_input || {},
+        event: payload.event || "tool.execute.before",
+        sessionId: payload.session_id,
+      };
+    default:
+      return {
+        tool: payload.tool || payload.tool_name || "unknown",
+        params: payload.params || payload.args || payload.tool_input || {},
+        event: payload.event || "pre_tool_use",
+        sessionId: payload.session_id,
+      };
+  }
+}
+
+// ─── Output Formatting ──────────────────────────────────────────────────────
+
+function formatOutput(result, framework, original) {
+  const { allowed, reason } = result;
+
+  switch (framework) {
+    case "claude":
+      return {
+        hookSpecificOutput: {
+          hookEventName: original.hook_event_name || "PreToolUse",
+          permissionDecision: allowed ? "allow" : "deny",
+          ...(allowed ? {} : { permissionDecisionReason: reason }),
+        },
+      };
+
+    case "cursor":
+      return {
+        permission: allowed ? "allow" : "deny",
+        ...(allowed ? {} : { reason }),
+      };
+
+    case "gemini":
+      return {
+        decision: allowed ? "allow" : "deny",
+        ...(allowed ? {} : { reason }),
+      };
+
+    case "hermes":
+      if (allowed) return {};
+      return { action: "block", message: reason };
+
+    case "opencode":
+      return {
+        block: !allowed,
+        ...(allowed ? {} : { reason }),
+      };
+
+    default:
+      return {
+        allow: allowed,
+        ...(allowed ? {} : { reason, reflection: result.reflection }),
+      };
+  }
+}
+
+// ─── Audit Trail ────────────────────────────────────────────────────────────
+
+function auditLog(event, tool, params, result) {
+  try {
+    if (!fs.existsSync(AUDIT_DIR)) {
+      fs.mkdirSync(AUDIT_DIR, { recursive: true });
+    }
+    const entry = {
+      ts: new Date().toISOString(),
+      event,
+      tool,
+      params,
+      result,
+    };
+    fs.appendFileSync(AUDIT_LOG, JSON.stringify(entry) + "\n");
+  } catch {
+    // Silent fail — audit logging should never block enforcement
+  }
+}
+
+// ─── Main Hook ──────────────────────────────────────────────────────────────
+
+const ENFORCER = new EnforcerClient();
+
+/**
+ * Process a tool call through the character hook.
+ *
+ * @param {object} payload - Raw tool call from framework
+ * @param {object} options - { framework: "auto"|"claude"|..., enforcer: EnforcerClient }
+ * @returns {Promise<{output: object, exitCode: number}>}
+ */
+export async function processToolCall(payload, options = {}) {
+  const framework = options.framework === "auto"
+    ? detectFramework(payload)
+    : (options.framework || "generic");
+
+  const enforcer = options.enforcer || ENFORCER;
+  const normalized = normalizeInput(payload, framework);
+
+  // Skip enforcer internal calls
+  if (["validate_workspace", "heartbeat", "execute_tool"].includes(normalized.tool)) {
+    return { output: formatOutput({ allowed: true }, framework, payload), exitCode: 0 };
+  }
+
+  // Fail-closed by default: if the enforcer can't be reached, block.
+  // Opt out only in development with ACK_FAIL_OPEN=1 (never in production).
+  const failClosed = !process.env.ACK_FAIL_OPEN;
+
+  const isPre = [
+    "pre_tool_use", "pretooluse", "beforetool",
+    "pre_tool_call", "tool.execute.before"
+  ].includes(normalized.event);
+
+  let result;
+  if (isPre) {
+    result = await enforcer.validateTool(
+      normalized.tool,
+      normalized.params,
+      normalized.sessionId || "unknown"
+    );
+
+    // Enforcer unreachable → enforce the closed posture.
+    if (result.error && !failClosed) {
+      result = { allowed: true };
+    }
+
+    auditLog("pre_tool_use", normalized.tool, normalized.params, result);
+  } else {
+    auditLog("post_tool_use", normalized.tool, normalized.params, payload.result);
+    result = { allowed: true };
+  }
+
+  const output = formatOutput(result, framework, payload);
+  const exitCode = !result.allowed && ["claude", "cursor", "gemini"].includes(framework) ? 2 : 0;
+
+  return { output, exitCode };
+}
+
+/**
+ * Generate framework-specific hook configuration.
+ */
+export function generateConfig(framework, hookCommand) {
+  const cmd = hookCommand || "npx aik hook";
+
+  switch (framework) {
+    case "claude":
+      return {
+        hooks: {
+          PreToolUse: [{
+            matcher: "*",
+            hooks: [{ type: "command", command: `${cmd} --framework claude` }],
+          }],
+        },
+      };
+
+    case "cursor":
+      return {
+        version: 1,
+        hooks: {
+          preToolUse: [{ command: `${cmd} --framework cursor`, matcher: "*" }],
+        },
+      };
+
+    case "gemini":
+      return {
+        hooks: {
+          BeforeTool: [{
+            matcher: ".*",
+            hooks: [{
+              name: "character-enforcer",
+              type: "command",
+              command: `${cmd} --framework gemini`,
+            }],
+          }],
+        },
+      };
+
+    case "hermes":
+      return `# Add to your Hermes plugin:
+const { processToolCall } = require("agent-character-kit");
+
+ctx.register_hook("pre_tool_call", async (toolName, args, taskId) => {
+  const result = await processToolCall(
+    { tool_name: toolName, args, task_id: taskId },
+    { framework: "hermes" }
+  );
+  return result.output;
+});
+`;
+
+    case "opencode":
+      return `// Add to your OpenCode plugin:
+import { processToolCall } from "agent-character-kit";
+
+export default async ({ tool, args }) => {
+  const result = await processToolCall(
+    { tool, args },
+    { framework: "opencode" }
+  );
+  return result.output;
+};
+`;
+
+    default:
+      return {
+        hooks: {
+          pre_tool_use: [{ command: `${cmd} --framework generic` }],
+        },
+      };
+  }
+}

package/node/src/index.js

@@ -0,0 +1,24 @@
+/**
+ * Agent Character Kit
+ *
+ * Core: Character hook enforcement via enforcer daemon
+ * Secondary: Knowledge indexing + memory with YAML frontmatter
+ *
+ * Every document gets proper YAML frontmatter for efficient searching.
+ * Every tool call gets validated through the enforcer.
+ */
+
+// ─── Core: Character Enforcement ─────────────────────────────────────────────
+
+export { EnforcerClient } from "./enforcer/client.js";
+export { processToolCall, generateConfig } from "./hooks/character.js";
+
+// ─── Secondary: Knowledge & Memory ──────────────────────────────────────────
+
+export { DocumentIndexer } from "./knowledge/indexer.js";
+export { SemanticSearch } from "./knowledge/semantic.js";
+export { Memory, DailyNotes, WeeklyDigest, LongTermMemory, KnowledgeGraph } from "./memory/index.js";
+
+// ─── Version ────────────────────────────────────────────────────────────────
+
+export const VERSION = "1.0.0";