{"_id":"@bizrk/agent-ledger","_rev":"3-68d7f5071ccd9e460d100ee59dcaced5","name":"@bizrk/agent-ledger","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@bizrk/agent-ledger","version":"0.1.0","_id":"@bizrk/agent-ledger@0.1.0","maintainers":[{"name":"bizrk","email":"adam@birkner.dev"}],"dist":{"shasum":"884e5a70778acdff553e95cbec8f4e788fb543ce","tarball":"https://registry.npmjs.org/@bizrk/agent-ledger/-/agent-ledger-0.1.0.tgz","fileCount":28,"integrity":"sha512-ZAF/4HRBXYv903OWY/n2QNeQ7hx7vtlONV42Jw1Iiuo5TEtBp27tlJlTbcg6vjCVegvcgEXuMZMgeA+MAklQFg==","signatures":[{"sig":"MEUCIQCIMbD7GIRb4aX/m3kNn/X+BVcsar2W8IJo4xpOMuBC+wIgJ7GlPAqJsoPzUO5ayeD+Wp5y1mMqB0JOem09UQmrc8o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47155},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"dev":"tsc -w","build":"tsc"},"_npmUser":{"name":"bizrk","email":"adam@birkner.dev"},"_npmVersion":"10.9.4","description":"Core runtime logic and buffer for Agent Ledger","directories":{},"_nodeVersion":"22.22.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-ledger_0.1.0_1776704941631_0.5200015051840046","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bizrk/agent-ledger","version":"0.1.1","_id":"@bizrk/agent-ledger@0.1.1","maintainers":[{"name":"bizrk","email":"adam@birkner.dev"}],"dist":{"shasum":"c6f7cdf4e56758f9fe5c40e253b60e43000a02e6","tarball":"https://registry.npmjs.org/@bizrk/agent-ledger/-/agent-ledger-0.1.1.tgz","fileCount":28,"integrity":"sha512-5dWF9DhFrcs6Sh76kiVGwEsTvqYREzlgM6VfmX7ATR7JXKCHin5z+aIgQdMNahdP64ufPgNVg/R/CQsEITAfRg==","signatures":[{"sig":"MEUCIB77mNaH788t60eOKtMBXFrm4tC+2MkTuL3yUnfXLiLcAiEA5wY1KMSYQhCwHKc1gLozkM4RVOanjnWG7/rlyNii808=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47166},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"dev":"tsc -w","build":"tsc"},"_npmUser":{"name":"bizrk","email":"adam@birkner.dev"},"_npmVersion":"10.9.4","description":"Core runtime logic and buffer for Agent Ledger","directories":{},"_nodeVersion":"22.22.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-ledger_0.1.1_1776710155523_0.7307007982001041","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@bizrk/agent-ledger","version":"0.1.2","description":"Core runtime logic and buffer for Agent Ledger","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc -w"},"dependencies":{},"devDependencies":{"typescript":"^5.0.0"},"_id":"@bizrk/agent-ledger@0.1.2","gitHead":"1083fc63aee9bfc54658523825b6174443144fc0","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-sd1IL/ZFOx28cDa2rJWOYCe1UE2AxgRxLWkMjd2oH0AoX0R2+BkOP5eke/ddG0v6jwzxJYuOG2eVGFjA9kLfRA==","shasum":"aefb9d52822025e07bf2cfdbf9b30dc6936f5511","tarball":"https://registry.npmjs.org/@bizrk/agent-ledger/-/agent-ledger-0.1.2.tgz","fileCount":27,"unpackedSize":34602,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCAU7XuwtcE4jg8/JZlTQunvdi6baH/gEPjg/xhJtil0wIgfbsCTL8FM4VRkOsdAWPDh6lpwJ5BOH0Gqx5ByFdjEi4="}]},"_npmUser":{"name":"bizrk","email":"adam@birkner.dev"},"directories":{},"maintainers":[{"name":"bizrk","email":"adam@birkner.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-ledger_0.1.2_1776711147038_0.833084441635328"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-20T17:09:01.438Z","modified":"2026-04-20T18:52:27.318Z","0.1.0":"2026-04-20T17:09:01.777Z","0.1.1":"2026-04-20T18:35:55.723Z","0.1.2":"2026-04-20T18:52:27.200Z"},"description":"Core runtime logic and buffer for Agent Ledger","maintainers":[{"name":"bizrk","email":"adam@birkner.dev"}],"readme":"# Agent Ledger\n\nAgent Ledger is a runtime logging system designed for strict, AI-friendly, and filterable application logs. It's not just a console wrapper—it behaves as an in-memory runtime ledger that records application behavior across both core host applications and decoupled plugins/products without losing structured state.\n\nIt optimizes for:\n*   **Predictable Structuring**: All entries adhere strictly to a `LedgerEntry` format (`level`, `product`, `category`, `source`, `message`, `metadata`).\n*   **Scoped Defaults**: Deep nesting features allow you to construct loggers scoped to a flow or file, removing the need to repeatedly pass boilerplate strings.\n*   **Opt-In Safety**: Configurable enablement functions allow client-side logs to remain totally silent without crashing unless explicitly activated (e.g. through specific query parameters and cookies).\n\n## Packages\nThe functionality is split across two main packages in the monorepo:\n*   `agent-ledger` — The core runtime, types, buffer, and logic.\n*   `agent-ledger-web` — Optional browser helpers specifically for reading URLs, syncing debug cookies, and formatting to `console.log`.\n\n---\n\n## 1. Global Setup & Enablement (Host App)\n\nAgent Ledger must be configured *once* globally by the host application early in the lifecycle.\n\nIf you are running in a browser, use the `agent-ledger-web` helpers for URL-driven enablement. For example, ensuring logs never output on `localhost` unless a developer explicitly triggers `?agentledger=true` first:\n\n```ts\nimport { configureAgentLedger, getAgentLedger } from 'agent-ledger';\nimport { \n  getBrowserContext, \n  parseBrowserOverrides, \n  hasDebugCookie, \n  setupConsoleOutput, \n  emitStartupBanner, \n  syncDebugCookie \n} from 'agent-ledger-web';\n\n// Optional: Mount the styled terminal output formatter \nsetupConsoleOutput();\n\n// Sync opt-in query param (e.g. `?agentledger=true`) to a persistent cookie.\n// If a user hits `?agentledger=false`, the cookie is deleted. \nconst SECRET_COOKIE_NAME = 'bizrk_ledger_auth';\nsyncDebugCookie(SECRET_COOKIE_NAME, 'agentledger');\n\n// Read current URL shapes and the newly persisted cookie\nconst browserContext = getBrowserContext();\nconst overrides = parseBrowserOverrides(); // Pulls ?debug=... params\n\n// Configure the engine\nconfigureAgentLedger({\n  defaultProduct: 'site-core',\n  level: 'debug', // Default minimum level\n  categories: ['app', 'flow', 'nav', 'ui', 'error'],\n  outputs: ['console', 'buffer'], // Where logs get routed\n  allowLogging: () => {\n    // Only output if they have previously enabled the secret cookie!\n    return hasDebugCookie(SECRET_COOKIE_NAME, browserContext);\n  }\n}, overrides);\n\n// Output configuration to console cleanly\nemitStartupBanner();\n```\n\n---\n\n## 2. Using the Loggers\n\nAgent ledger loggers automatically swallow calls when logging is disabled, meaning you **never** have to write `if (logsEnabled) { ... }` wrappers in your product components. Note: Error objects passed as metadata are automatically and safely preserved!\n\n### The Default Logger\nIf you ask for a default logger, it automatically assumes your `defaultProduct` boundary.\n\n```ts\nimport { getAgentLedger } from 'agent-ledger';\n\nconst logger = getAgentLedger();\n\n// Unscoped Call Signature:\n// logger.<level>(category, source, message, metadata?)\n\nlogger.info('nav', 'router', 'Navigated to simulated page', { path: '/home' });\nlogger.debug('ui', 'button', 'User clicked UI element', { x: 100, y: 200 });\nlogger.error('error', 'app', 'Simulated failure occurred', new Error('Something broke!'));\n```\n\n### Plugin / Product Registration\nIf you are writing a sub-module or plugin within the app, you can register it independently and fetch its own bound logger.\n\n```ts\nimport { registerAgentLedgerProduct, getAgentLedger } from 'agent-ledger';\n\n// Register the product (idempotent, doesn't crash if repeated)\nregisterAgentLedgerProduct({ product: 'leancss' });\n\n// Get a logger permanently bound to the product\nconst pluginLogger = getAgentLedger('leancss');\n```\n\n### Scoping Contexts\nTo avoid constantly repeating categories and sources across a file, you can `scope` a logger down infinitely.\n\n```ts\n// Scope to a specific source boundary and category!\nconst compileLogger = getAgentLedger('leancss').scope({\n  source: 'Compiler.run',\n  category: 'flow'\n});\n\n// Because 'source' and 'category' are both bound, the shape shrinks to just (message, metadata)\ncompileLogger.info('start', { fileCount: 12 });\ncompileLogger.info('complete', { outputFiles: 8 });\n```\n\n---\n\n## 3. Metadata Redaction\n\nAgent Ledger automatically intercepts the payload before it enters the `buffer` or `console` and masks sensitive data. If any keys inside your metadata dictionary match standard vulnerable strings (like `password`, `token`, `authorization`, `cookie`), their values are scrubbed and replaced with `[REDACTED]`. \n\nIf an `Error` object is passed into metadata, it successfully extracts the `stack`, `message`, and `name` properties to ensure they serialize properly and don't collapse when stringified.\n\n---\n\n## 4. The In-Memory Ledger Buffer\n\nWhen the `buffer` output is enabled in configuration, logs populate an internal rolling ring-buffer (capable of retaining recent events in-memory up to a maximum size). \n\nThis allows you to easily pull a JSON payload or formatted text directly from the developer console (or AI Agent prompts) at runtime!\n\n```ts\nimport { globalBuffer } from 'agent-ledger';\n\n// Output an AI-friendly plaintext summary of current application flow\nconsole.log(globalBuffer.exportText());\n\n// Output strict JSON telemetry\nconsole.log(globalBuffer.exportJSON());\n```\n\n---\n\n## 5. URL Debug Testing API\nWhen utilizing the `agent-ledger-web` browser package, the router supports the following native query structures to dynamically filter system logging without touching code:\n\n*   `?agentledger=true` — Sets a cookie activating the whole system (as implemented in setup)\n*   `?debugLevel=trace` — Overrides the global configuration to output everything down to trace.\n*   `?debugCategories=flow,error` — Mutes all telemetry *except* flow and error levels.\n*   `?debug=leancss` — Mutes the core system and focuses telemetry *only* on the LeanCSS product logs.\n*   `?debug=true` — Un-mutes product filtering entirely, defaulting back to all available products.\n","readmeFilename":"README.md"}