hammer-ai 0.2.0

package/dist/node.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Base Memory Layer — shared infrastructure for memory compaction.
+ *
+ * Both workspace agents and the Voice Agent use episodic compaction with
+ * structured state extraction. This module provides the shared skeleton:
+ *
+ * - Generic base class (`BaseMemoryLayer<TState, TMessage>`)
+ * - Shared types: `MemoryMessage`, `CompactionCursor`, `MemoryStorage`, etc.
+ * - Token estimation strategy (pluggable: tiktoken vs char-based)
+ * - Shared algorithms: sliding-window, buildMessages, triggerCompaction
+ *
+ * Core Invariants (enforced by this base):
+ * 1. Raw history is NEVER modified in-place; entries are pruned after compaction
+ * 2. Compaction is a state transition, not a view transform
+ * 3. Compressed state is NEVER recursively summarized
+ * 4. State compaction removes obsolete structure but preserves meaning
+ * 5. buildMessages is a PURE function (cache writes are benign memoization)
+ */
+
+/** Base message stored in raw history. */
+interface MemoryMessage {
+    id: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    timestamp: number;
+    /** Monotonic message counter. */
+    turn: number;
+    /** Cached token count for this message (computed once at creation). */
+    tokenCount: number;
+}
+/**
+ * Strategy for estimating token counts.
+ *
+ * - Workspace agents share the same estimator strategy by default
+ * - CharTokenEstimator is the cross-platform baseline implementation
+ */
+interface TokenEstimator {
+    /** Estimate token count for a string. */
+    estimateTokens(text: string): number;
+    /** Dispose any resources (e.g. tiktoken WASM). No-op by default. */
+    dispose?(): void;
+}
+
+/**
+ * Precise token estimator using tiktoken (cl100k_base encoding).
+ *
+ * Separated into its own module so environments can opt into the tiktoken WASM
+ * dependency explicitly. Browser runtimes should reach it through async
+ * estimator helpers instead of importing it from hot paths.
+ */
+
+declare class TiktokenEstimator implements TokenEstimator {
+    private encoder;
+    constructor();
+    estimateTokens(text: string): number;
+    dispose(): void;
+}
+
+/**
+ * Shared conversation history utilities.
+ *
+ * Provides:
+ * - `atomicWriteJSON()` — crash-safe file writing (tmp + rename)
+ * - `ConversationHistoryEntry` — debug-friendly message format
+ * - `formatConversationHistory()` — converts MemoryMessages to debug entries
+ *
+ * Used by:
+ * - Voice agent (Bun server writes conversation_history.json alongside voice-memory.json)
+ * - Hammer agent (ConversationManager, UnifiedAgent)
+ *
+ * NOTE: Server-only module (requires Node/Bun fs). Not imported by browser/mobile code.
+ */
+
+/**
+ * Atomically write JSON data to a file using tmp + rename.
+ *
+ * 1. Creates parent directories if needed
+ * 2. Writes to `filePath.tmp`
+ * 3. Renames to `filePath` (atomic on most filesystems)
+ *
+ * Prevents data corruption if the process crashes mid-write.
+ */
+declare function atomicWriteJSON(filePath: string, data: unknown): Promise<void>;
+/** Debug-friendly conversation history entry. */
+interface ConversationHistoryEntry {
+    turn: number;
+    role: string;
+    content: string;
+    timestamp: number;
+    id?: string;
+    tokenCount?: number;
+}
+/**
+ * Convert raw MemoryMessages to a flat, debug-friendly array.
+ *
+ * The output is designed for easy reading in a JSON viewer — no nested
+ * compressed-state or cursor objects. Each entry is one message with
+ * its turn number, role, content, and timestamp.
+ */
+declare function formatConversationHistory(messages: MemoryMessage[]): ConversationHistoryEntry[];
+
+export { type ConversationHistoryEntry, TiktokenEstimator, atomicWriteJSON, formatConversationHistory };

package/dist/node.js

@@ -0,0 +1,47 @@
+import { encoding_for_model } from 'tiktoken';
+import { mkdir, writeFile, rename } from 'fs/promises';
+import { dirname } from 'path';
+
+// src/tiktoken-estimator.ts
+var TiktokenEstimator = class {
+  encoder;
+  constructor() {
+    try {
+      this.encoder = encoding_for_model("gpt-4");
+    } catch (err) {
+      throw new Error(
+        `Failed to initialize tiktoken encoder (WASM may not be available in this environment): ${err instanceof Error ? err.message : err}`
+      );
+    }
+  }
+  estimateTokens(text) {
+    if (!this.encoder) throw new Error("TiktokenEstimator has been disposed");
+    return this.encoder.encode(text).length;
+  }
+  dispose() {
+    if (this.encoder) {
+      this.encoder.free();
+      this.encoder = null;
+    }
+  }
+};
+async function atomicWriteJSON(filePath, data) {
+  await mkdir(dirname(filePath), { recursive: true });
+  const tmpFile = filePath + ".tmp";
+  await writeFile(tmpFile, JSON.stringify(data, null, 2), "utf-8");
+  await rename(tmpFile, filePath);
+}
+function formatConversationHistory(messages) {
+  return messages.map((m) => ({
+    turn: m.turn,
+    role: m.role,
+    content: m.content,
+    timestamp: m.timestamp,
+    ...m.id ? { id: m.id } : {},
+    ...m.tokenCount ? { tokenCount: m.tokenCount } : {}
+  }));
+}
+
+export { TiktokenEstimator, atomicWriteJSON, formatConversationHistory };
+//# sourceMappingURL=node.js.map
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tiktoken-estimator.ts","../src/conversation-history-writer.ts"],"names":[],"mappings":";;;;;AAWO,IAAM,oBAAN,MAAkD;AAAA,EAC7C,OAAA;AAAA,EAER,WAAA,GAAc;AACV,IAAA,IAAI;AACA,MAAA,IAAA,CAAK,OAAA,GAAU,mBAAmB,OAAO,CAAA;AAAA,IAC7C,SAAS,GAAA,EAAK;AACV,MAAA,MAAM,IAAI,KAAA;AAAA,QACN,CAAA,uFAAA,EAA0F,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,UAAU,GAAG,CAAA;AAAA,OACtI;AAAA,IACJ;AAAA,EACJ;AAAA,EAEA,eAAe,IAAA,EAAsB;AACjC,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,EAAS,MAAM,IAAI,MAAM,qCAAqC,CAAA;AACxE,IAAA,OAAO,IAAA,CAAK,OAAA,CAAQ,MAAA,CAAO,IAAI,CAAA,CAAE,MAAA;AAAA,EACrC;AAAA,EAEA,OAAA,GAAgB;AACZ,IAAA,IAAI,KAAK,OAAA,EAAS;AACd,MAAA,IAAA,CAAK,QAAQ,IAAA,EAAK;AAClB,MAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AAAA,IACnB;AAAA,EACJ;AACJ;ACDA,eAAsB,eAAA,CAClB,UACA,IAAA,EACa;AACb,EAAA,MAAM,MAAM,OAAA,CAAQ,QAAQ,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAClD,EAAA,MAAM,UAAU,QAAA,GAAW,MAAA;AAC3B,EAAA,MAAM,SAAA,CAAU,SAAS,IAAA,CAAK,SAAA,CAAU,MAAM,IAAA,EAAM,CAAC,GAAG,OAAO,CAAA;AAC/D,EAAA,MAAM,MAAA,CAAO,SAAS,QAAQ,CAAA;AAClC;AAuBO,SAAS,0BACZ,QAAA,EAC0B;AAC1B,EAAA,OAAO,QAAA,CAAS,GAAA,CAAI,CAAC,CAAA,MAAO;AAAA,IACxB,MAAM,CAAA,CAAE,IAAA;AAAA,IACR,MAAM,CAAA,CAAE,IAAA;AAAA,IACR,SAAS,CAAA,CAAE,OAAA;AAAA,IACX,WAAW,CAAA,CAAE,SAAA;AAAA,IACb,GAAI,EAAE,EAAA,GAAK,EAAE,IAAI,CAAA,CAAE,EAAA,KAAO,EAAC;AAAA,IAC3B,GAAI,EAAE,UAAA,GAAa,EAAE,YAAY,CAAA,CAAE,UAAA,KAAe;AAAC,GACvD,CAAE,CAAA;AACN","file":"node.js","sourcesContent":["/**\n * Precise token estimator using tiktoken (cl100k_base encoding).\n *\n * Separated into its own module so environments can opt into the tiktoken WASM\n * dependency explicitly. Browser runtimes should reach it through async\n * estimator helpers instead of importing it from hot paths.\n */\n\nimport { encoding_for_model, type Tiktoken } from \"tiktoken\"\nimport type { TokenEstimator } from \"./memory-layer\"\n\nexport class TiktokenEstimator implements TokenEstimator {\n    private encoder: Tiktoken | null\n\n    constructor() {\n        try {\n            this.encoder = encoding_for_model(\"gpt-4\")\n        } catch (err) {\n            throw new Error(\n                `Failed to initialize tiktoken encoder (WASM may not be available in this environment): ${err instanceof Error ? err.message : err}`,\n            )\n        }\n    }\n\n    estimateTokens(text: string): number {\n        if (!this.encoder) throw new Error(\"TiktokenEstimator has been disposed\")\n        return this.encoder.encode(text).length\n    }\n\n    dispose(): void {\n        if (this.encoder) {\n            this.encoder.free()\n            this.encoder = null\n        }\n    }\n}\n","/**\n * Shared conversation history utilities.\n *\n * Provides:\n * - `atomicWriteJSON()` — crash-safe file writing (tmp + rename)\n * - `ConversationHistoryEntry` — debug-friendly message format\n * - `formatConversationHistory()` — converts MemoryMessages to debug entries\n *\n * Used by:\n * - Voice agent (Bun server writes conversation_history.json alongside voice-memory.json)\n * - Hammer agent (ConversationManager, UnifiedAgent)\n *\n * NOTE: Server-only module (requires Node/Bun fs). Not imported by browser/mobile code.\n */\n\n/// <reference types=\"node\" />\n\nimport { writeFile, rename, mkdir } from \"fs/promises\"\nimport { dirname } from \"path\"\nimport type { MemoryMessage } from \"./memory-layer\"\n\n// ============================================================================\n// Atomic File Writing\n// ============================================================================\n\n/**\n * Atomically write JSON data to a file using tmp + rename.\n *\n * 1. Creates parent directories if needed\n * 2. Writes to `filePath.tmp`\n * 3. Renames to `filePath` (atomic on most filesystems)\n *\n * Prevents data corruption if the process crashes mid-write.\n */\nexport async function atomicWriteJSON(\n    filePath: string,\n    data: unknown,\n): Promise<void> {\n    await mkdir(dirname(filePath), { recursive: true })\n    const tmpFile = filePath + \".tmp\"\n    await writeFile(tmpFile, JSON.stringify(data, null, 2), \"utf-8\")\n    await rename(tmpFile, filePath)\n}\n\n// ============================================================================\n// Conversation History\n// ============================================================================\n\n/** Debug-friendly conversation history entry. */\nexport interface ConversationHistoryEntry {\n    turn: number\n    role: string\n    content: string\n    timestamp: number\n    id?: string\n    tokenCount?: number\n}\n\n/**\n * Convert raw MemoryMessages to a flat, debug-friendly array.\n *\n * The output is designed for easy reading in a JSON viewer — no nested\n * compressed-state or cursor objects. Each entry is one message with\n * its turn number, role, content, and timestamp.\n */\nexport function formatConversationHistory(\n    messages: MemoryMessage[],\n): ConversationHistoryEntry[] {\n    return messages.map((m) => ({\n        turn: m.turn,\n        role: m.role,\n        content: m.content,\n        timestamp: m.timestamp,\n        ...(m.id ? { id: m.id } : {}),\n        ...(m.tokenCount ? { tokenCount: m.tokenCount } : {}),\n    }))\n}\n"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "hammer-ai",
+    "version": "0.2.0",
+    "description": "Infrastructure for building tool-calling bash-format chat agents: LLM client, agent loop, memory, tool registry, validation, and web runtime.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./node": {
+            "types": "./dist/node.d.ts",
+            "import": "./dist/node.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "clean": "rm -rf dist",
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "keywords": [
+        "ai",
+        "agent",
+        "llm",
+        "tool-calling",
+        "bash",
+        "agentic-loop",
+        "memory",
+        "compaction"
+    ],
+    "author": "",
+    "license": "MIT",
+    "dependencies": {
+        "xstate": "5",
+        "zod": "^3.25.76"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "tiktoken": "^1.0.22",
+        "tsup": "^8.4.0",
+        "typescript": "^5.9.0"
+    },
+    "peerDependencies": {
+        "tiktoken": "^1.0.22"
+    },
+    "peerDependenciesMeta": {
+        "tiktoken": {
+            "optional": true
+        }
+    }
+}