microcoreos 0.2.2__tar.gz → 0.3.1__tar.gz

microcoreos-0.3.1/.env.example

@@ -0,0 +1,191 @@
+# ╔════════════════════════════════════════════════════════════════════════════╗
+# ║  MicroCoreOS — every environment variable, with its default.               ║
+# ║                                                                            ║
+# ║  This file is the REFERENCE: commented options belong here.                ║
+# ║  Your .env is STATE: only settings in effect, none commented out.          ║
+# ║                                                                            ║
+# ║  `microcoreos add <extra>` appends a section like these to your .env, so   ║
+# ║  leaving a variable commented there makes it get appended a second time.   ║
+# ╚════════════════════════════════════════════════════════════════════════════╝
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  HTTP SERVER                                            tools/http_server  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+HTTP_PORT=5000
+
+# Bind address. Default: 127.0.0.1 (dev-safe).
+# PRODUCTION / DOCKER: must be 0.0.0.0 or the service refuses external connections.
+# HTTP_HOST=0.0.0.0
+
+# CORS allowed origins. Default: * (dev-friendly).
+# Production: your actual frontend domain(s), comma-separated.
+# HTTP_CORS_ORIGINS=https://app.example.com,https://admin.example.com
+
+# Let cross-origin requests carry cookies. Default: false. Needed only when a
+# browser app on ANOTHER origin authenticates by cookie instead of by Bearer
+# token. Requires an explicit HTTP_CORS_ORIGINS list — the tool refuses to boot
+# with '*', which would authorize every site to send the session cookie.
+# HTTP_CORS_CREDENTIALS=true
+
+# Uvicorn log level. Default: warning. Set to info for HTTP access logs.
+# HTTP_LOG_LEVEL=info
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  DATABASE — SQLite                                           tools/sqlite  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+SQLITE_DB_PATH=database.db
+
+# Migrations policy. Default: true (boot applies pending migrations).
+# PRODUCTION: migrating from a replica is PROHIBITED — set false in EVERY
+# replica. Migrations run ONLY as a CI/CD step, in a SINGLE instance, under
+# explicit human supervision:
+#   DB_AUTO_MIGRATE=true uv run main.py --boot-tool db
+# DB_AUTO_MIGRATE=false
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  EVENT BUS                                                tools/event_bus  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# Driver. Default: in_process (same-process, zero infrastructure).
+# Options: in_process | sqlite | redis_streams | kafka | rabbitmq
+# The last two need `microcoreos add kafka` / `add rabbitmq` — see their sections.
+# EVENT_BUS_DRIVER=in_process
+
+# Dead-letter queue for events that exhausted their retries. Default: true.
+# EVENT_BUS_DLQ_ENABLED=false
+
+# --- sqlite driver: durable queue on disk, no broker ---
+# EVENT_BUS_SQLITE_PATH=event_bus_queue.db
+# EVENT_BUS_SQLITE_MAXLEN=10000        # rows kept per stream
+# EVENT_BUS_SQLITE_POLL_MS=25          # consumer poll interval
+# EVENT_BUS_SQLITE_SYNCHRONOUS=FULL    # FULL | NORMAL — NORMAL is faster, less durable
+
+# --- redis_streams driver: also needs the REDIS section below ---
+# EVENT_BUS_STREAM_MAXLEN=10000        # entries kept per stream
+# EVENT_BUS_CLAIM_IDLE_MS=60000        # ms before a stalled message is reclaimed
+# EVENT_BUS_DELAY_POLL_MS=500          # delayed-delivery poll interval
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  TELEMETRY — OpenTelemetry                                tools/telemetry  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# ALL tool calls get spans automatically via ToolProxy — no plugin changes.
+# Install first:
+#   uv add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-fastapi
+OTEL_ENABLED=false
+OTEL_SERVICE_NAME=microcoreos
+
+# Export destination. Commented = console exporter (dev).
+# Jaeger, Grafana Tempo, or any OTLP/gRPC backend.
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+
+# BatchSpanProcessor tuning (OTel standard vars)
+# OTEL_BSP_SCHEDULE_DELAY=5000         # ms between export batches
+# OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512   # spans per batch
+# OTEL_BSP_MAX_QUEUE_SIZE=2048         # in-memory buffer size
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  HEALTH CHECK                                              domains/system  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# ToolHealthPlugin calls db.health_check() periodically and updates the registry.
+HEALTH_CHECK_INTERVAL=30
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  METRICS                                                        always on  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# Timing needs no config — ToolProxy measures every tool call:
+#   records = self.registry.get_metrics()
+#   self.registry.add_metrics_sink(callback)
+# Each record: {tool, method, duration_ms, success, timestamp}
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  AUTHENTICATION                                      microcoreos add auth  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# AUTH_SECRET_KEY=change-me                # REQUIRED, 32 chars minimum
+# AUTH_TOKEN_EXPIRE_MINUTES=60
+# AUTH_ALGORITHM=HS256
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  DATABASE — PostgreSQL                           microcoreos add postgres  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# Replaces the sqlite tool: the LAST one to register wins the 'db' key.
+# PG_HOST=localhost
+# PG_PORT=5432
+# PG_USER=postgres
+# PG_PASSWORD=postgres
+# PG_DATABASE=microcoreos
+# PG_MIN_POOL=1
+# PG_MAX_POOL=10
+# PG_CONNECT_TIMEOUT=5
+# PG_COMMAND_TIMEOUT=30
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  REDIS                                              microcoreos add redis  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# Swaps the in-memory state tool. For the Redis Streams EVENT BUS instead,
+# set EVENT_BUS_DRIVER=redis_streams — that driver already ships in tools/event_bus/.
+# REDIS_HOST=localhost
+# REDIS_PORT=6379
+# REDIS_DB=0
+# REDIS_PASSWORD=                          # empty for no auth
+# REDIS_CONNECT_TIMEOUT=5
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  S3 STORAGE                                            microcoreos add s3  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# AWS_ACCESS_KEY_ID=your-access-key
+# AWS_SECRET_ACCESS_KEY=your-secret-key
+# AWS_DEFAULT_REGION=us-east-1
+# AWS_S3_ENDPOINT_URL=http://localhost:9000    # MinIO in dev; drop for real S3
+# AWS_S3_DEFAULT_BUCKET=microcoreos-bucket
+# AWS_S3_SIZE_LIMIT_ENABLED=true
+# AWS_S3_MAX_FILE_SIZE_MB=10
+# AWS_S3_VERIFY_SSL=true
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  SCHEDULER                                      microcoreos add scheduler  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# false on worker replicas: jobs register everywhere, fire in ONE beat replica.
+# SCHEDULER_ENABLED=true
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  KAFKA                                              microcoreos add kafka  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# EVENT_BUS_DRIVER=kafka
+# KAFKA_BOOTSTRAP_SERVERS=localhost:9092
+# KAFKA_BUS_TOPIC_PREFIX=bus.
+# KAFKA_BUS_PARTITIONS=6
+# KAFKA_BUS_REPLICATION=1
+# KAFKA_CONNECT_TIMEOUT=5
+# KAFKA_MAX_POLL_INTERVAL_MS=300000
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  RABBITMQ                                        microcoreos add rabbitmq  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# EVENT_BUS_DRIVER=rabbitmq
+# RABBITMQ_HOST=localhost
+# RABBITMQ_PORT=5672
+# RABBITMQ_USER=guest
+# RABBITMQ_PASSWORD=guest
+# RABBITMQ_VHOST=/
+# RABBITMQ_PREFETCH=16
+# RABBITMQ_CONNECT_TIMEOUT=5
+
+# ╭────────────────────────────────────────────────────────────────────────────╮
+# │  CHAOS ENGINEERING                                  microcoreos add chaos  │
+# ╰────────────────────────────────────────────────────────────────────────────╯
+
+# Intentionally fails tools/plugins on boot to test fault tolerance.
+# NEVER enable in production.
+# CHAOS_ENABLED=true

{microcoreos-0.2.2 → microcoreos-0.3.1}/.gitignore

@@ -55,3 +55,10 @@ package-lock.json
 # as a submodule with no .gitmodules, and every checkout since failed its
 # cleanup step with exit 128.
 .claude/worktrees/
+
+# Test Coverage & Mutation Testing
+.coverage
+htmlcov/
+.mutmut-cache/
+mutants/
+

{microcoreos-0.2.2 → microcoreos-0.3.1}/AI_CONTEXT.md

@@ -23,7 +23,8 @@ HTTP Server Tool (http):
           'data' = flat merge of [path params] + [query params] + [body/form fields].
           Special keys in 'data':
             - data["_auth"]: contains the payload from auth_validator if successful.
-            - data["_files"]: list of FastAPI UploadFile objects (only if has_files=True).
+            - data["_files"]: list of UploadedFile objects (only if has_files=True).
+                Fields: .filename, .content_type, .stream (sync file object), await .read().
         - SECURITY DEFAULTS:
             - Cookies set via context.set_cookie are 'Secure=True', 'HttpOnly=True', 'SameSite=Lax'.
             - CSRF Guard: Mutations (POST/PUT/DELETE) using cookie auth REQUIRE 'X-Requested-With' header.
@@ -35,8 +36,19 @@ HTTP Server Tool (http):
                 - has_files: if True, enables multipart/form-data. Request model fields 
                   become Form fields. To use a file: file = data["_files"][0]; 
                   await s3.upload_fileobj(file.filename, file.file, content_type=file.content_type)
-            - mount_static(path, directory_path): Serve static files from a directory.
-            - add_ws_endpoint(path, on_connect, on_disconnect=None): WebSocket support.
+            - mount_static(path, directory_path, html=False, allow_extensions=None):
+                Serve static files from a directory. Deny by default: only files whose
+                extension is allowed are served (default DEFAULT_STATIC_EXTENSIONS; pass
+                a set to declare your own, or "*" to serve everything). Dotfiles are
+                always refused except under '.well-known/'. Use html=True to serve
+                index.html for directory requests, which a UI/SPA mounted at "/" needs.
+                Raises ValueError if the directory does not exist.
+            - add_ws_endpoint(path, on_connect, on_disconnect=None, auth_validator=None):
+                WebSocket support. on_connect receives a WebSocketConnection: send_text,
+                send_json, receive_text, receive_json, close, query_params, path_params.
+                With auth_validator the token is read from the Authorization header, the
+                `token` query param, then the access_token cookie; an invalid one is
+                closed with 1008 BEFORE the handshake and on_connect takes (conn, payload).
             - add_sse_endpoint(path, generator, tags=None, auth_validator=None):
                 Server-Sent Events. generator yields formatted strings: "data: {...}\n\n".
             - register_pre_mount_hook(hook): hook(endpoints: list[dict]) is called once in
@@ -286,6 +298,33 @@ Async SQLite Persistence Tool (sqlite):
 
 ## 📦 Domains
 
+### `chaos`
+- **Tables**: none
+- **Endpoints**:
+  - `GET /system/chaos`
+    - **res**: ChaosStateData(faults: list[FaultSpecView(tool: str, source: str, mode: str, plugin: Optional[str], rate: Optional[float], seconds: Optional[float])], wrapped_tools: list[str], paused_plugins: list[str])
+  - `POST /system/chaos/fail`
+    - **req**: plugin: str, tool: Optional[str], rate: float
+    - **res**: FailData(plugin: str, tool: Optional[str], rate: float)
+  - `POST /system/chaos/latency`
+    - **req**: plugin: Optional[str], tool: Optional[str], seconds: float
+    - **res**: LatencyData(plugin: Optional[str], tool: Optional[str], seconds: float)
+  - `POST /system/chaos/off`
+    - **req**: plugin: str
+    - **res**: PluginPauseData(plugin: str, paused: bool)
+  - `POST /system/chaos/on`
+    - **req**: plugin: str
+    - **res**: PluginPauseData(plugin: str, paused: bool)
+  - `POST /system/chaos/reset`
+    - **res**: ResetData(cleared: int, restored_tools: list[str], resumed_plugins: list[str])
+  - `POST /system/chaos/tool`
+    - **req**: name: str, mode: Literal['down', 'slow', 'flaky', 'off'], seconds: float, rate: float
+    - **res**: ToolFaultData(name: str, mode: str)
+- **Events emitted**: `system.chaos.fail_armed` (plugin, rate, tool), `system.chaos.latency_armed` (plugin, seconds, tool), `system.chaos.plugin_paused` (plugin), `system.chaos.plugin_resumed` (plugin), `system.chaos.reset` (cleared), `system.chaos.tool_fault_armed` (mode, tool)
+- **Events consumed**: none
+- **Dependencies**: container, event_bus, http, logger
+- **Plugins**: chaos.ChaosControlPlugin
+
 ### `devtools`
 - **Tables**: none
 - **Endpoints**:

{microcoreos-0.2.2 → microcoreos-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microcoreos
-Version: 0.2.2
+Version: 0.3.1
 Summary: Atomic Microkernel Architecture optimized for AI-Driven Development
 License: MIT
 License-File: LICENSE
@@ -9,6 +9,7 @@ Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: pydantic[email]>=2.10.0
 Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: websockets>=13.0

{microcoreos-0.2.2 → microcoreos-0.3.1}/extras/available_tools/auth/auth_tool.py

@@ -28,6 +28,8 @@ REPLACEMENT STANDARD (plugins unaffected):
        from decode_token. validate_token returns None instead of raising.
 """
 
+import base64
+import hashlib
 import os
 import asyncio
 import bcrypt
@@ -37,6 +39,20 @@ from typing import Optional
 from microcoreos import BaseTool
 
 
+def _prehash(password: str) -> bytes:
+    """
+    bcrypt hashes at most 72 bytes and stops at the first NUL, both silently:
+    two passwords sharing a 72-byte prefix verify against the same hash.
+    Hashing first makes every input a fixed 44-byte, NUL-free digest, so the
+    whole password decides the result. base64 rather than hex to stay well
+    under the limit. This is passlib's bcrypt_sha256 construction.
+
+    Changing this function invalidates every stored hash — they can only be
+    reissued by a password reset, since the plaintext is not recoverable.
+    """
+    return base64.b64encode(hashlib.sha256(password.encode("utf-8")).digest())
+
+
 class AuthError(Exception):
     """Base class for authentication failures."""
 
@@ -74,9 +90,12 @@ class AuthTool(BaseTool):
         - PURPOSE: Manage system security, password hashing, and JWT token lifecycle.
         - CAPABILITIES:
             - await hash_password(password: str) -> str: Securely hashes a plain-text
-                password using bcrypt. Async — runs in a thread (bcrypt is CPU-bound).
+                password: SHA-256 first, then bcrypt, so the whole password counts
+                regardless of length (bare bcrypt silently ignores everything past
+                72 bytes). Async — runs in a thread (bcrypt is CPU-bound).
             - await verify_password(password: str, hashed_password: str) -> bool:
                 Verifies if a password matches its hash. Async — runs in a thread.
+                Only hashes produced by this tool's hash_password() verify.
             - create_token(data: dict, expires_delta: Optional[int] = None) -> str:
                 Generates a JWT signed token. 'data' should contain claims (e.g. {'sub': user_id}).
                 'expires_delta' is optional minutes until expiration.
@@ -92,12 +111,12 @@ class AuthTool(BaseTool):
         # bcrypt is CPU-bound (~100ms by design) — run in a thread so it
         # never blocks the event loop under concurrent requests.
         return await asyncio.to_thread(
-            lambda: bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
+            lambda: bcrypt.hashpw(_prehash(password), bcrypt.gensalt()).decode()
         )
 
     async def verify_password(self, password: str, hashed_password: str) -> bool:
         return await asyncio.to_thread(
-            bcrypt.checkpw, password.encode(), hashed_password.encode()
+            bcrypt.checkpw, _prehash(password), hashed_password.encode()
         )
 
     def create_token(self, data: dict, expires_delta: Optional[int] = None) -> str:

{microcoreos-0.2.2 → microcoreos-0.3.1}/extras/available_tools/scheduler/scheduler_tool.py

@@ -12,6 +12,10 @@ PUBLIC CONTRACT (what plugins use):
     job_id = scheduler.add_job("0 * * * *", self.on_every_hour)
     job_id = scheduler.add_job("*/5 * * * *", self.send_digest, job_id="digest")
 
+    # Recurring job — fixed interval, for the sub-minute rates cron cannot express
+    job_id = scheduler.add_interval_job(1.0, self.sample_metrics)
+    job_id = scheduler.add_interval_job(0.25, self.poll, job_id="poll", max_instances=4)
+
     # One-shot job — runs once at a specific datetime
     from datetime import datetime, timedelta, timezone
     run_at = datetime.now(timezone.utc) + timedelta(minutes=30)
@@ -86,13 +90,23 @@ REPLACEMENT STANDARD (swap without changing plugins):
     To replace with Celery beat or any other scheduler:
     1. Create tools/{name}/{name}_tool.py
     2. Set name = "scheduler"                    ← same injection key
-    3. Implement the 4 public methods:
+    3. Implement the 5 public methods:
          add_job(cron_expr, callback, job_id?) → str
+         add_interval_job(seconds, callback, job_id?, ...) → str
          add_one_shot(run_at, callback, job_id?) → str
          remove_job(job_id) → bool
          list_jobs() → list[dict]
     4. Honor SCHEDULER_ENABLED (jobs register everywhere, fire in one place).
     Plugins do not change.
+
+    LIMIT OF THIS CONTRACT: every method above takes a Python callable, so it
+    is implementable only by a scheduler running IN THIS PROCESS (APScheduler,
+    `schedule`, a bare asyncio loop). Celery beat and every other distributed
+    beat dispatch task NAMES to a broker for other processes to run, and a
+    bound method does not cross a process boundary. Distributed scheduling is
+    reached the other way — by scheduling an EVENT rather than a function:
+    "scheduler.one_shot.schedule" on the bus, where everything crossing the
+    boundary is JSON. See durable_one_shots_plugin.py.
 """
 
 import functools
@@ -170,7 +184,11 @@ class SchedulerTool(BaseTool):
     def setup(self) -> None:
         try:
             from apscheduler.schedulers.asyncio import AsyncIOScheduler
+            from apscheduler.events import EVENT_JOB_MISSED, EVENT_JOB_MAX_INSTANCES
             self._scheduler = AsyncIOScheduler()
+            self._scheduler.add_listener(
+                self._on_run_dropped, EVENT_JOB_MISSED | EVENT_JOB_MAX_INSTANCES
+            )
             print("[Scheduler] APScheduler initialized.")
         except ImportError:
             raise RuntimeError(
@@ -188,6 +206,23 @@ class SchedulerTool(BaseTool):
         self._scheduler.start()
         print(f"[Scheduler] Started — {job_count} job(s) registered.")
 
+    def _on_run_dropped(self, event) -> None:
+        """
+        APScheduler discards runs without raising: one past its misfire grace
+        time (EVENT_JOB_MISSED) or one that would exceed max_instances
+        (EVENT_JOB_MAX_INSTANCES) never reaches the callback and returns no
+        error to anybody. Unlogged, a job firing less often than it was
+        configured to is indistinguishable from one firing correctly.
+        """
+        from apscheduler.events import EVENT_JOB_MAX_INSTANCES
+
+        reason = ("overlapped a still-running execution (max_instances)"
+                  if event.code == EVENT_JOB_MAX_INSTANCES
+                  else "was later than its misfire_grace_time")
+        # JobExecutionEvent carries scheduled_run_time; JobSubmissionEvent, a list.
+        when = getattr(event, "scheduled_run_time", None) or getattr(event, "scheduled_run_times", None)
+        print(f"[Scheduler] Run DROPPED — id={event.job_id!r} {reason}, scheduled for {when}")
+
     def shutdown(self) -> None:
         if self._scheduler and self._scheduler.running:
             self._scheduler.shutdown(wait=False)
@@ -229,6 +264,75 @@ class SchedulerTool(BaseTool):
         print(f"[Scheduler] Job registered — id={job_id!r} cron={cron_expr!r}")
         return job_id
 
+    def add_interval_job(
+        self,
+        seconds: float,
+        callback: Callable,
+        job_id: Optional[str] = None,
+        *,
+        minutes: float = 0,
+        hours: float = 0,
+        max_instances: int = 1,
+        coalesce: bool = True,
+        misfire_grace_time: Optional[int] = 1,
+    ) -> str:
+        """
+        Schedule a recurring job on a fixed interval.
+
+        Cron's smallest unit is the minute, so anything faster — and any rate
+        that is not a whole number of minutes — has to be an interval.
+
+        Parameters:
+            seconds:  Interval in seconds; accepts fractions (0.25 = 4x/second).
+                      Combined additively with minutes and hours.
+            callback: Sync or async callable. Called with no arguments.
+            job_id:   Optional stable ID. Auto-generated if omitted.
+
+        The last three mirror APScheduler's job defaults and matter as the
+        interval approaches the callback's own duration:
+
+            max_instances:      concurrent runs allowed. At 1, a run starting
+                                while the previous one is still going is
+                                DROPPED, not queued.
+            coalesce:           collapse several missed runs into one.
+            misfire_grace_time: seconds late a run may start; past that it is
+                                DROPPED. None means run it however late.
+
+        Dropped runs raise nothing — they are reported by _on_run_dropped().
+        A job that must not skip needs max_instances above 1, a callback
+        faster than the interval, or both.
+
+        Returns: the job_id string.
+
+        Examples:
+            scheduler.add_interval_job(1.0, self.sample_metrics)
+            scheduler.add_interval_job(0.25, self.poll, job_id="poll", max_instances=4)
+            scheduler.add_interval_job(0, self.hourly, minutes=90)
+        """
+        from apscheduler.triggers.interval import IntervalTrigger
+
+        if seconds <= 0 and minutes <= 0 and hours <= 0:
+            raise ValueError(
+                "add_interval_job: interval must be positive — "
+                f"got seconds={seconds}, minutes={minutes}, hours={hours}"
+            )
+
+        job_id = job_id or uuid.uuid4().hex
+        self._scheduler.add_job(
+            _with_identity(callback),
+            trigger=IntervalTrigger(seconds=seconds, minutes=minutes, hours=hours),
+            id=job_id,
+            replace_existing=True,
+            max_instances=max_instances,
+            coalesce=coalesce,
+            misfire_grace_time=misfire_grace_time,
+        )
+        print(
+            f"[Scheduler] Interval job registered — id={job_id!r} "
+            f"every {seconds}s+{minutes}m+{hours}h max_instances={max_instances}"
+        )
+        return job_id
+
     def add_one_shot(
         self,
         run_at: datetime,
@@ -307,6 +411,15 @@ class SchedulerTool(BaseTool):
                 e.g. "*/5 * * * *" = every 5 min, "0 9 * * 1-5" = weekdays at 09:00.
                 Returns job_id (auto-generated if not provided).
                 Providing a stable job_id prevents duplicates on restart.
+            - add_interval_job(seconds: float, callback, job_id?: str, *, minutes, hours,
+                               max_instances=1, coalesce=True, misfire_grace_time=1) -> str:
+                Schedule a recurring job on a fixed interval. Use this for sub-minute
+                rates, which a 5-field cron expression cannot express (its unit is the
+                minute). seconds accepts fractions: 0.25 = 4x/second.
+                At max_instances=1 a run that overlaps the previous one is DROPPED, and
+                a run later than misfire_grace_time is DROPPED — silently, as far as the
+                callback is concerned. Both are logged as "Run DROPPED". Raise
+                max_instances if the job must not skip.
             - add_one_shot(run_at: datetime, callback, job_id?: str) -> str:
                 Schedule a one-time job at a specific datetime (timezone-aware).
                 Returns job_id. IN-MEMORY: lost if the process restarts before firing.

{microcoreos-0.2.2 → microcoreos-0.3.1}/microcoreos/catalog.py

@@ -174,12 +174,48 @@ def _install_dependency(extra: str, root: str) -> bool:
     return True
 
 
+ENV_BOX_WIDTH = 76
+
+
+def _env_section_header(title: str, source: str) -> list:
+    """
+    One boxed heading per tool, so .env stays readable as extras accumulate.
+    .env.example uses this same function; keep the three lines equal in width
+    or the boxes stop lining up.
+    """
+    left = f"  {title}"
+    pad = ENV_BOX_WIDTH - len(left) - len(source) - 2
+    return [
+        f"# ╭{'─' * ENV_BOX_WIDTH}╮",
+        f"# │{left}{' ' * max(pad, 1)}{source}  │",
+        f"# ╰{'─' * ENV_BOX_WIDTH}╯",
+    ]
+
+
+def _env_state(existing: str, var: str) -> str:
+    """Whether var is absent, set, or present but commented out."""
+    for line in existing.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(f"{var}="):
+            return "set"
+        if stripped.startswith("#") and stripped.lstrip("#").strip().startswith(f"{var}="):
+            return "commented"
+    return "absent"
+
+
 def _append_env(root: str, name: str, entries) -> None:
     """
     Append the extra's settings to .env, once.
 
     Anything already defined there is the user's decision and is left alone —
     re-running `add` must never rewrite a password someone typed.
+
+    A commented-out setting counts as already there. It is not appended again:
+    python-dotenv gives precedence to the LAST occurrence, so the duplicate
+    would override the line above it and editing that line would do nothing.
+    Which of the two the user meant is not knowable here — commenting a
+    variable reads equally as "I want the default" and as "I will fill this in
+    later" — so the choice is reported rather than made.
     """
     if not entries:
         return
@@ -189,12 +225,18 @@ def _append_env(root: str, name: str, entries) -> None:
     if os.path.exists(path):
         existing = open(path, encoding="utf-8").read()
 
-    missing = [e for e in entries if f"\n{e[0]}=" not in f"\n{existing}"]
+    states = {e[0]: _env_state(existing, e[0]) for e in entries}
+    missing = [e for e in entries if states[e[0]] == "absent"]
+    commented = [v for v, s in states.items() if s == "commented"]
+
+    for var in commented:
+        print(f"   ! .env has {var} commented out — uncomment it or delete the line.")
+
     if not missing:
         print("   ✓ .env already has these settings — unchanged.")
         return
 
-    block = [f"\n# ─── {name} (added by `microcoreos add {name}`) ───"]
+    block = [""] + _env_section_header(name.upper(), f"microcoreos add {name}") + [""]
     for var, value, comment in missing:
         block.append(f"{var}={value}" + (f"   # {comment}" if comment else ""))
 

{microcoreos-0.2.2 → microcoreos-0.3.1}/microcoreos/scaffold.py

@@ -376,6 +376,62 @@ def _install_test_deps(root: str) -> bool:
     return True
 
 
+def _write_initial_env(example_path: str, env_path: str) -> None:
+    """
+    Initializes .env from .env.example.
+
+    `.env.example` is the reference containing all commented options for extras.
+    `.env` is active state: only settings in effect, omitting commented-out
+    optional extra settings so that `microcoreos add <extra>` can append them cleanly.
+    """
+    from microcoreos.catalog import CATALOG
+
+    extra_vars = {
+        var for extra in CATALOG.values() if extra.env for var, _, _ in extra.env
+    }
+
+    with open(example_path, encoding="utf-8") as f:
+        lines = f.readlines()
+
+    out_lines = []
+    skip_section = False
+
+    for line in lines:
+        stripped = line.strip()
+
+        # Omit commented-out settings for optional extras
+        if stripped.startswith("#") and any(
+            stripped.lstrip("#").strip().startswith(f"{var}=") for var in extra_vars
+        ):
+            continue
+
+        # Omit section header boxes for optional extras
+        if stripped.startswith("# │") and "microcoreos add" in stripped:
+            skip_section = True
+            if out_lines and "# ╭──" in out_lines[-1]:
+                out_lines.pop()
+            continue
+
+        if skip_section and ("# ╰──" in stripped or "# │" in stripped):
+            if "# ╰──" in stripped:
+                skip_section = False
+            continue
+
+        out_lines.append(line)
+
+    cleaned = []
+    prev_blank = False
+    for line_item in out_lines:
+        is_blank = not line_item.strip()
+        if is_blank and prev_blank:
+            continue
+        cleaned.append(line_item)
+        prev_blank = is_blank
+
+    with open(env_path, "w", encoding="utf-8") as f:
+        f.writelines(cleaned)
+
+
 def new(argv: list[str]) -> int:
     """`microcoreos new <path> [--force] [--no-ai-kit] [--no-install]`"""
     force = "--force" in argv
@@ -405,7 +461,7 @@ def new(argv: list[str]) -> int:
     # .env is configuration, not source: never clobber one that exists.
     env, example = os.path.join(target, ".env"), os.path.join(target, ".env.example")
     if os.path.exists(example) and not os.path.exists(env):
-        shutil.copy2(example, env)
+        _write_initial_env(example, env)
 
     name = os.path.basename(target).replace("_", "-").lower() or "my-app"