govyn 0.0.1 → 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GovynAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,265 @@
 # Govyn
 
-Coming soon.
+**The governance proxy for AI agents. Not an SDK. Not a wrapper. A wall.**
+
+Every other agent governance tool is a library you import. If your agent — or any code it touches — makes a direct HTTP call, governance disappears. Govyn is different. It's an API proxy that holds your real API keys. Your agents only get a proxy URL. There is no alternative path to the real API. Governance is enforced by architecture, not by convention.
+
+```
+SDK MODEL:
+Agent [has real API key] → tries wrapper → OpenAI API
+Agent [has real API key] → skips wrapper → OpenAI API  ← governance bypassed
+
+PROXY MODEL:
+Agent [no real API key] → Govyn Proxy [has real key, enforces rules] → OpenAI API
+Agent [no real API key] → OpenAI API directly → REJECTED (no key)
+```
+
+SDK governance is a door lock — effective until someone finds another door.
+Govyn is a wall. There are no other doors.
+
+---
+
+## Features
+
+- **Per-agent budgets** — Set daily/monthly spend limits per agent with hard (block) or soft (warn) enforcement
+- **Cost tracking** — Real-time cost aggregation across OpenAI, Anthropic, and compatible providers
+- **Loop detection** — Automatically detect and block agents stuck in repetitive call patterns
+- **Policy engine** — YAML-based rules: rate limits, model restrictions, require-approval gates, and custom policies
+- **Action logging** — Every request logged with agent identity, cost, tokens, latency, and full context
+- **Multi-provider** — Route OpenAI and Anthropic traffic through a single proxy with per-provider API keys
+- **Locked-down management API** — Local-only by default, with optional admin API key and browser origin allowlist for remote dashboards
+- **Zero agent changes** — Agents just point at a different base URL. No SDK imports, no code changes
+- **Fail-open by default** — Proxy errors don't break your agents. Configurable to fail-closed for high-security deployments
+
+## Quickstart
+
+Get from zero to a governed API call in under 5 minutes.
+
+### Prerequisites
+
+- Node.js 20+
+- An LLM API key (OpenAI or Anthropic)
+
+### Install and Configure
+
+```bash
+npx govyn init
+```
+
+The wizard walks you through provider selection, API key configuration, budget limits, agent naming, and persistence. It produces a local `govyn.config.yaml` in the current directory, defaults `database.url` to `sqlite:./govyn.db`, and can also point at PostgreSQL if you already run one.
+
+### Start the Proxy
+
+```bash
+npx govyn
+```
+
+The proxy starts on port 4000 by default.
+
+### Docker
+
+```bash
+docker run -p 4000:4000 -e OPENAI_API_KEY=sk-... govyn
+```
+
+Or with Docker Compose:
+
+```bash
+docker-compose up
+```
+
+For persistent self-hosting, mount a volume for your runtime files (`govyn.config.yaml`, `govyn.auth.json`, `govyn.db`, `policies.yaml`, and `logs/`) or point `database.url` at PostgreSQL instead of the default SQLite file.
+
+### Verify
+
+```bash
+curl http://localhost:4000/health
+# {"status":"ok"}
+```
+
+### Make Your First Governed Request
+
+```bash
+curl http://localhost:4000/v1/openai/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "X-Govyn-Agent: my-first-agent" \
+  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+The proxy forwards to OpenAI, tracks cost, enforces budget limits, and logs the action — all transparently.
+
+## Python SDK
+
+For Python agents, use the `govynai` package for drop-in wrappers around the OpenAI and Anthropic SDKs:
+
+```bash
+pip install govynai[all]
+```
+
+```python
+from govynai import GovynOpenAI
+
+client = GovynOpenAI(agent_id="my-agent")
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+The wrapper automatically routes through your Govyn proxy, injects agent headers, and surfaces governance errors as typed exceptions. See [`python-sdk/`](./python-sdk/) for full documentation.
+
+## Configuration
+
+Govyn uses a local `govyn.config.yaml` runtime file. Run `npx govyn init` to generate one interactively in your working directory, or create one manually. The repo ships example templates under [`configs/`](./configs/); it does not ship a ready-to-use operator config.
+
+`govyn.config.yaml` is your deployment file. Keep it local to your environment and do not treat it as a shared repo sample.
+
+The OSS dashboard also uses a local `govyn.auth.json` file for its single admin account. Create it during `npx govyn init` or later with `npx govyn admin setup`. Keep that file local and out of git too.
+
+Govyn now uses SQLite by default for persistence. The default runtime database is `./govyn.db`, which powers approvals, alerts, cost history, and other durable operational data on a single host. Keep that file local and out of git too.
+
+For the smallest local-only starting point, use [`configs/openai-only.yaml`](./configs/openai-only.yaml) or generate one with `npx govyn init`. A minimal manual config looks like this:
+
+```yaml
+version: 1
+proxy:
+  port: 4000
+  host: 127.0.0.1
+
+providers:
+  openai:
+    base_url: https://api.openai.com
+    api_key_env: OPENAI_API_KEY
+  anthropic:
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+
+agents:
+  research-agent: {}
+
+database:
+  url: sqlite:./govyn.db
+
+budgets:
+  research-agent:
+    daily_limit: 10.00
+    monthly_limit: 100.00
+    limit_type: hard
+```
+
+If you omit `database.url`, Govyn still defaults to `sqlite:./govyn.db` beside your config. Keeping it explicit in your local config makes the deployment shape clearer.
+
+If you expose the proxy off-machine, add your own generated `agents.<name>.api_keys`. If you manage the proxy from a remote dashboard, create the local admin account on the host and add the dashboard origin under `security.trusted_origins`. Only set `security.admin_api_key_env` if you also want automation or break-glass API access.
+
+## Dashboard Auth
+
+- The OSS dashboard uses one local admin username/password account.
+- There is no Clerk, no email-based reset flow, no signup, and no OIDC/SAML in this repo.
+- Create the admin account with `npx govyn admin setup`, or let `npx govyn init` create it during first-run setup.
+- Reset the password locally with `npx govyn admin reset-password`.
+- Browser logins use an `HttpOnly` session cookie. `GOVYN_ADMIN_API_KEY` remains available for automation and break-glass recovery, not normal dashboard sign-in.
+
+## Persistence
+
+- Default OSS self-hosting: `database.url: sqlite:./govyn.db`
+- SQLite is the recommended default for one host, one admin, and the normal self-hosted OSS setup.
+- SQLite powers approvals, alerts, cost history, and other durable operational state without requiring a separate database service.
+- Switch to PostgreSQL by setting `database.url: postgres://...` when you need a shared database, managed backups, or multiple Govyn instances against the same backend.
+- The example configs under [`configs/`](./configs/) show the SQLite default and include commented PostgreSQL upgrade hints.
+
+See [`configs/openai-only.yaml`](./configs/openai-only.yaml) for the canonical minimal example, or browse [`configs/`](./configs/) for more setups (single provider, multi-provider, teams).
+
+## Security Defaults
+
+- Govyn does not ship any real agent keys, admin keys, or provider secrets. Every key shown in docs or UI is a placeholder or generated locally for the operator to adopt.
+- The proxy binds to `127.0.0.1` by default so a fresh install is local-only.
+- If you bind the proxy to a non-loopback host such as `0.0.0.0`, Govyn automatically requires `Authorization: Bearer <agent-api-key>` on proxied model requests. Configure those keys under `agents.<name>.api_keys`.
+- You can explicitly set `security.require_agent_api_key: false`, but that creates an unauthenticated spend surface and is unsafe on shared or public networks.
+- `/api/*` management endpoints are restricted to local requests by default.
+- Once the local dashboard admin exists, browser management uses the dashboard session cookie instead of a pasted API key.
+- To manage the proxy from another browser origin, add that origin under `security.trusted_origins` and sign in with the local admin username/password.
+- `GOVYN_ADMIN_API_KEY` (or another env var via `security.admin_api_key_env`) is for automation, CLI tooling, and break-glass remote API access via `X-Govyn-Admin-Key`.
+- Browser dashboards must be explicitly listed under `security.trusted_origins`. Localhost origins are allowed automatically for development.
+- Browser-origin management requests from untrusted origins are rejected even on localhost, which blocks CSRF-style admin actions against a developer machine.
+- `GET /api/approvals/:id` remains accessible without admin auth so the approval polling flow continues to work for agents.
+- Approval tokens are single-use and bound to the original approved agent, target path, and request body.
+- Alert webhooks reject loopback and private-network destinations, resolve DNS before connect, and block redirects to prevent SSRF against internal services.
+
+### Generating Agent Keys
+
+- Generate your own long random value for every agent. Do not reuse provider API keys as agent API keys.
+- The dashboard Settings page includes a browser-local generator and copy-ready YAML snippet. It helps you prepare local config only; it does not write proxy config, and the generated key is not sent to the proxy unless you manually add it to your config.
+- If you prefer the terminal, `node -e "console.log('gvn_' + require('node:crypto').randomBytes(32).toString('hex'))"` prints a suitable key.
+
+## Policy Engine
+
+Define governance rules in `policies.yaml`:
+
+```yaml
+policies:
+  - name: require-approval-for-gpt4
+    match:
+      model: "gpt-4*"
+    action: require_approval
+    message: "GPT-4 usage requires human approval"
+
+  - name: block-production-models-at-night
+    match:
+      model: "gpt-4o"
+    schedule:
+      deny: "0 22 * * *-0 6 * * *"
+    action: block
+```
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Health check |
+| `GET /api/costs` | Cost summaries per agent |
+| `GET /api/budgets` | Budget status and remaining limits |
+| `GET /api/logs` | Query action logs |
+| `GET /api/policies` | List active policies |
+| `POST /v1/openai/...` | Proxied OpenAI requests |
+| `POST /v1/anthropic/...` | Proxied Anthropic requests |
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────────────────────────┐     ┌─────────────┐
+│   Agent A    │────▶│          Govyn Proxy             │────▶│   OpenAI    │
+│  (no key)    │     │                                  │     │   API       │
+└─────────────┘     │  ┌──────────┐  ┌──────────────┐  │     └─────────────┘
+                    │  │ Policy   │  │ Budget       │  │
+┌─────────────┐     │  │ Engine   │  │ Enforcer     │  │     ┌─────────────┐
+│   Agent B    │────▶│  └──────────┘  └──────────────┘  │────▶│  Anthropic  │
+│  (no key)    │     │  ┌──────────┐  ┌──────────────┐  │     │   API       │
+└─────────────┘     │  │ Loop     │  │ Action       │  │     └─────────────┘
+                    │  │ Detector │  │ Logger       │  │
+┌─────────────┐     │  └──────────┘  └──────────────┘  │
+│   Agent C    │────▶│                                  │
+│  (no key)    │     │  Real API keys live here only    │
+└─────────────┘     └──────────────────────────────────┘
+```
+
+Agents never hold real API keys. The proxy is the only path to the real APIs.
+
+## Project Structure
+
+```
+govyn/
+├── src/              # Proxy server (TypeScript)
+├── python-sdk/       # Python SDK (govynai package)
+├── configs/          # Example configurations
+├── templates/        # Init wizard templates
+├── tests/            # Proxy test suite
+└── docs/             # Documentation
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on submitting pull requests, reporting issues, and development setup.
+
+## License
+
+[MIT](./LICENSE) — Copyright (c) 2026 GovynAI

package/configs/multi-provider.yaml

@@ -0,0 +1,68 @@
+# Govyn Config: Multi-Provider
+# OpenAI + Anthropic + a custom local LLM (Ollama), two agents with different budgets.
+
+version: 1
+
+proxy:
+  port: 4000
+  host: 127.0.0.1                       # Local-only default. For remote exposure, change this to 0.0.0.0 and add your own agent API keys.
+
+providers:
+  openai:
+    base_url: https://api.openai.com
+    api_key_env: OPENAI_API_KEY
+
+  anthropic:
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+
+  custom:
+    ollama:
+      base_url: http://localhost:11434    # Local Ollama instance
+      # No api_key_env needed for local Ollama
+
+agents:
+  research-agent:
+    # Add your own generated api_keys only if you expose the proxy off-machine.
+    # api_keys:
+    #   - gvn_generate_your_own_long_random_secret_here
+  coding-agent:
+    # api_keys:
+    #   - gvn_generate_your_own_second_long_random_secret_here
+
+database:
+  url: sqlite:./govyn.db                # Default OSS persistence for approvals, alerts, and history.
+  # For a shared/team deployment later, switch to PostgreSQL:
+  # url: postgres://govyn:change-me@db.example.com:5432/govyn
+
+# Custom pricing for models not in the built-in pricing table
+pricing:
+  llama3:
+    input: 0.00                           # Free for local models
+    output: 0.00
+
+budgets:
+  research-agent:
+    daily_limit: 10.00
+    monthly_limit: 200.00
+    limit_type: hard
+    soft_warning_percent: 80
+
+  coding-agent:
+    daily_limit: 25.00
+    monthly_limit: 500.00
+    limit_type: soft                      # Soft limit: warn but don't block
+    soft_warning_percent: 70
+
+security:
+  # Only needed for remote dashboard or admin API access.
+  # admin_api_key_env: GOVYN_ADMIN_API_KEY
+  # trusted_origins:
+  #   - https://dashboard.example.com
+
+logging:
+  enabled: true
+  directory: ./logs
+  default_mode: metadata
+  stdout: true
+  file: true

package/configs/openai-only.yaml

@@ -0,0 +1,45 @@
+# Govyn Config: OpenAI-Only
+# Minimal setup for proxying OpenAI requests with a single agent and daily budget.
+
+version: 1
+
+proxy:
+  port: 4000
+  host: 127.0.0.1                       # Local-only default. For remote exposure, change this to 0.0.0.0 and add your own agent API key.
+
+providers:
+  openai:
+    base_url: https://api.openai.com    # Default OpenAI API endpoint
+    api_key_env: OPENAI_API_KEY          # Reads from this environment variable
+
+agents:
+  my-agent:
+    # Local-only example. If you expose the proxy on a non-loopback host,
+    # uncomment the lines below and generate your own long random secret.
+    # api_keys:
+    #   - gvn_generate_your_own_long_random_secret_here
+
+database:
+  url: sqlite:./govyn.db                # Default OSS persistence. Govyn creates this local SQLite file automatically.
+  # For a shared or managed database later, switch to PostgreSQL:
+  # url: postgres://govyn:change-me@db.example.com:5432/govyn
+
+budgets:
+  my-agent:
+    daily_limit: 5.00                    # Hard stop at $5/day
+    monthly_limit: 100.00                # Hard stop at $100/month
+    limit_type: hard                     # hard = block requests, soft = warn only
+    soft_warning_percent: 80             # Emit warning header at 80% usage
+
+security:
+  # Only needed for remote dashboard or admin API access.
+  # admin_api_key_env: GOVYN_ADMIN_API_KEY
+  # trusted_origins:
+  #   - https://dashboard.example.com
+
+logging:
+  enabled: true
+  directory: ./logs
+  default_mode: metadata                 # 'metadata' = summary only, 'full-payload' = include bodies
+  stdout: true                           # Print log lines to stdout (useful for Docker)
+  file: true                             # Write JSONL log files to disk

package/configs/team-setup.yaml

@@ -0,0 +1,88 @@
+# Govyn Config: Team Setup
+# Multi-agent team with soft/hard budgets and mixed logging modes.
+# Full-payload logging for the debug agent, metadata-only for others.
+
+version: 1
+
+proxy:
+  port: 4000
+  host: 127.0.0.1                       # Local-only default. For remote exposure, change this to 0.0.0.0 and add your own agent API keys.
+
+providers:
+  openai:
+    base_url: https://api.openai.com
+    api_key_env: OPENAI_API_KEY
+
+  anthropic:
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+
+agents:
+  frontend-agent:
+    # Add your own generated api_keys only if you expose the proxy off-machine.
+    # api_keys:
+    #   - gvn_generate_your_own_frontend_secret_here
+    loop_detection:
+      threshold: 5                        # Stricter loop detection for UI agents
+      window_seconds: 30
+      cooldown_seconds: 120
+
+  backend-agent:
+    # api_keys:
+    #   - gvn_generate_your_own_backend_secret_here
+    loop_detection:
+      threshold: 15                       # More lenient for batch processing
+      window_seconds: 60
+      cooldown_seconds: 300
+
+  debug-agent:
+    # api_keys:
+    #   - gvn_generate_your_own_debug_secret_here
+
+database:
+  url: sqlite:./govyn.db                # Default single-host persistence.
+  # For a shared team deployment or multiple Govyn instances, switch to PostgreSQL:
+  # url: postgres://govyn:change-me@db.example.com:5432/govyn
+
+budgets:
+  frontend-agent:
+    daily_limit: 5.00
+    monthly_limit: 50.00
+    limit_type: hard                      # Hard limit: block at threshold
+    soft_warning_percent: 80
+
+  backend-agent:
+    daily_limit: 20.00
+    monthly_limit: 400.00
+    limit_type: soft                      # Soft limit: warn but allow
+    soft_warning_percent: 70
+
+  debug-agent:
+    daily_limit: 2.00
+    monthly_limit: 20.00
+    limit_type: hard
+    soft_warning_percent: 90
+
+security:
+  # Only needed for remote dashboard or admin API access.
+  # admin_api_key_env: GOVYN_ADMIN_API_KEY
+  # trusted_origins:
+  #   - https://dashboard.example.com
+
+logging:
+  enabled: true
+  directory: ./logs
+  default_mode: metadata                  # Most agents get metadata-only logging
+  stdout: true
+  file: true
+  max_body_size: 524288                   # 512KB max body capture
+  rotation_max_size_mb: 25               # Rotate at 25MB (smaller for teams)
+  rotation_interval_hours: 12            # Rotate every 12 hours
+  retention_days: 14                     # Keep logs for 2 weeks
+  payload_retention_days: 3              # Keep payload files for 3 days
+
+  # Per-agent logging mode overrides
+  agent_modes:
+    debug-agent: full-payload             # Full request/response bodies for debugging
+    frontend-agent: metadata              # Summary only
+    backend-agent: metadata               # Summary only

package/dist/action-logger.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Async action logger for the Govyn proxy server.
+ *
+ * Writes structured JSONL log entries for every proxied request.
+ * Supports two modes:
+ * - metadata: summary fields only (default)
+ * - full-payload: stores request/response bodies as separate JSON files
+ *
+ * Design:
+ * - log() is synchronous and non-blocking (zero added latency)
+ * - Entries are buffered in memory and flushed to disk on a 1-second interval
+ * - storePayload() is fire-and-forget async (errors logged to stderr)
+ * - Dual output: stdout AND/OR file, either disableable in config
+ */
+import type { LogEntry, LoggingConfig, LoggingMode } from './types.js';
+/**
+ * ActionLogger writes structured JSONL log entries for proxied requests.
+ *
+ * Non-blocking by design: log() pushes to an in-memory buffer that is
+ * flushed to disk on a 1-second unref'd interval. storePayload() writes
+ * payload files asynchronously without awaiting in the request path.
+ */
+export declare class ActionLogger {
+    /** Exposed config for consumers that need to read settings (e.g., maxBodySize) */
+    readonly config: LoggingConfig;
+    /** Internal write buffer — entries waiting to be flushed to disk */
+    private buffer;
+    /** Path to the current active JSONL log file */
+    private currentFilePath;
+    /** Path to the payloads subdirectory */
+    private payloadsDir;
+    /** Periodic flush interval handle */
+    private flushInterval;
+    /** Log rotator for size/time-based rotation and retention cleanup */
+    private rotator;
+    constructor(config: LoggingConfig);
+    /**
+     * Read-only access to the log directory path.
+     * Used by the log query API to locate JSONL files.
+     */
+    get logDirectory(): string;
+    /**
+     * Get the full filesystem path to a payload file.
+     *
+     * @param payloadId - The payload ID (used as filename stem)
+     * @returns Full path to the payload JSON file
+     */
+    getPayloadPath(payloadId: string): string;
+    /**
+     * Log a structured entry. Non-blocking — adds to buffer and optionally writes to stdout.
+     * This is the zero-latency guarantee: no file I/O in the hot path.
+     * Automatically sets storage_region from config if not already set on the entry.
+     *
+     * @param entry - The structured log entry to record
+     */
+    log(entry: LogEntry): void;
+    /**
+     * Store a full payload (request + response bodies) as a separate JSON file.
+     * Fully async — fire and forget. Errors are logged to stderr but never thrown.
+     *
+     * @param payloadId - Unique ID for this payload (used as filename)
+     * @param requestBody - Raw request body buffer (or null)
+     * @param responseBody - Raw response body buffer (or null)
+     * @param truncated - Whether either body was truncated due to size limits
+     */
+    storePayload(payloadId: string, requestBody: Buffer | null, responseBody: Buffer | null, truncated: boolean): void;
+    /**
+     * Flush buffered entries to the current JSONL file.
+     * Uses synchronous append to ensure atomicity of the batch write.
+     */
+    flush(): void;
+    /**
+     * Get the logging mode for a specific agent.
+     * Returns the agent-specific override if set, otherwise the default mode.
+     *
+     * @param agentId - The agent to look up
+     * @returns The LoggingMode to use for this agent
+     */
+    getMode(agentId: string): LoggingMode;
+    /**
+     * Set the logging mode for a specific agent at runtime.
+     * Does NOT persist to YAML — runtime-only toggle.
+     *
+     * @param agentId - The agent to configure
+     * @param mode - The logging mode to set
+     */
+    setMode(agentId: string, mode: LoggingMode): void;
+    /**
+     * Get the path of the current active JSONL log file.
+     * Useful for rotation logic and diagnostics.
+     */
+    getCurrentFilePath(): string;
+    /**
+     * Purge all log entries and associated payload files older than the given date.
+     *
+     * - Reads all JSONL files (current + rotated) in the log directory
+     * - For each file: filters out entries with timestamps before the date
+     * - Deletes payload files for removed entries that have has_payload=true
+     * - Handles gzipped rotated files: decompress, filter, recompress or delete
+     * - Returns counts of deleted log entries and deleted payload files
+     *
+     * @param date - Purge entries with timestamps strictly before this date
+     * @returns Counts of deleted log entries and payload files
+     */
+    purgeBefore(date: Date): {
+        deletedLogs: number;
+        deletedPayloads: number;
+    };
+    /**
+     * Purge entries from a plain JSONL file.
+     * Rewrites the file with only entries newer than the cutoff date.
+     */
+    private purgeJsonlFile;
+    /**
+     * Purge entries from a gzipped rotated JSONL file.
+     * Decompresses, filters, and either recompresses or deletes if empty.
+     */
+    private purgeGzipFile;
+    /**
+     * Close the logger: flush remaining buffer and stop the flush interval.
+     */
+    close(): void;
+    /**
+     * Generate a unique ID for log entries and payload files.
+     * Uses crypto.randomUUID() for guaranteed uniqueness.
+     */
+    static generateId(): string;
+}