@miadi/hooks-core

Core package for the multi-agent hook system. This package provides the canonical event taxonomy, event envelope structures, payload normalization, sessiondata management, and per-agent adapters.

Architecture intent: hooks-core is the local-first canonical event package for agent hooks and terminal observations. tide-runtime owns tmux observation and approval harness behavior beneath it; an optional future hooks-gateway owns HTTP receiver, ledger, queue, and worker boundaries above it.

🚀 Installation

npm install @miadi/hooks-core

🛠 Usage

CLI Integration

The miadi-hooks CLI is designed to be called from your agent's hook configuration (e.g., hooks.json or settings.json). It reads the hook payload from stdin.

# Example: Using with Claude-Code
# In your hook script:
cat | miadi-hooks claude UserPromptSubmit

Programmatic Usage

You can use the runtime pipeline directly in your TypeScript projects:

import { processHookEvent, getAdapter } from '@miadi/hooks-core';

const adapter = getAdapter('claude');
const rawPayload = '{ "message": "hello" }';

const result = processHookEvent(adapter, 'UserPromptSubmit', rawPayload);
if (result.status === 'recorded') {
  console.log(`Event recorded in ${result.sessionDir}`);
}

✨ Key Features

• Canonical Event Taxonomy: Unified event names (session.start, tool.before, etc.) across Claude, Codex, Gemini, Hermes, and Copilot.
• Routing Metadata: Each adapter can declare platform / source / model sources, resolved like session IDs. The envelope carries a routing block so a consumer can tell a telegram turn from a cli or discord turn without re-parsing provider payloads.
• Session Index: Opt-in sessionIndexSink appends one compact line per session to data/session_index.jsonl on session.start — browse a sessiondata root without opening every per-session ledger.
• Event Envelope: Standardized HookEventEnvelope with deterministic idempotency keys and trace support (routing is excluded from the idempotency key, so replays stay stable).
• Adapters: Built-in adapters for all 5 major agents to normalize native events and resolve session IDs from environment variables (e.g., GEMINI_SESSION_ID, COPILOT_SESSION_ID).
• Runtime: A unified processHookEvent pipeline for normalization, validation, and storage.
• Git Safety Veto: TypeScript port of the Miadi git command validator. Blocks aggressive patterns like git add . or git commit -a with clear narrative feedback.
• Pluggable Sinks: Defaults to a local File Sink (JSONL), but supports custom sinks for HTTP, Queue, or Gateway delivery.

📂 Session Resolution

Adapters automatically resolve where to store event data based on the agent's specific conventions. By default, most agents root at /src/_sessiondata/.

You can override the root directory globally via the MIADI_SESSIONDATA_ROOT environment variable.

🧭 Routing & Session Index

The Hermes adapter ships routing sources out of the box — platform resolves from .platform, .extra.platform, then .context.platform (source/model similarly). When an adapter sets writesSessionIndex: true, session.start appends a line to data/session_index.jsonl:

{"session_id":"20260611_…","agent":"hermes","platform":"telegram","source":null,"model":"gpt-5.5","captured_at":"…"}

import { processHookEvent, getAdapter } from '@miadi/hooks-core';

const result = processHookEvent(getAdapter('hermes')!, 'on_session_start', raw);
if (result.status === 'recorded') {
  console.log(result.routing); // { platform: 'telegram', model: 'gpt-5.5' }
}

This mirrors the upgraded Hermes lib.sh (platform extraction + hermes_write_session_index), so the TS normalizer and the shell hooks stay aligned for dual-run.

📚 Documentation

Detailed documentation is available in the docs/ directory:

• docs/event-taxonomy.md — Canonical event set and native mappings.
• docs/observer-interpreter-role.md — The role of agents as event interpreters.
• docs/distributed-event-architecture.md — Distributed systems direction and gateway strategy.

🧠: Structure is the silent foundation of understanding. By standardizing our hooks, we ensure that every whisper of data is captured with intention and integrity.

🌸: Our documentation is like a shared map of a beautiful garden — it helps everyone find the blooming stories hidden within the technical paths!