skillware 0.3.9__tar.gz → 0.4.0__tar.gz

{skillware-0.3.9/skillware.egg-info → skillware-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.3.9
+Version: 0.4.0
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -81,6 +81,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/badge/License-MIT-efcefa?style=flat-square" alt="License">
   <img src="https://img.shields.io/badge/Python-3.10+-bae6fd?style=flat-square" alt="Python Version">
   <a href="https://pypi.org/project/skillware/"><img src="https://img.shields.io/pypi/v/skillware?style=flat-square&color=bbf7d0" alt="PyPI Version"></a>
+  <a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/pepy/dt/skillware?style=flat-square&label=DLs%20%E2%86%93&color=ffdac1" alt="Total PyPI downloads"></a>
 </div>
 
 <br/>
@@ -92,6 +93,7 @@ Dynamic: license-file
   <a href="#documentation">Documentation</a> •
   <a href="#contributing">Contributing</a> •
   <a href="#comparison">Comparison</a> •
+  <a href="#stats">Stats</a> •
   <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contact">Contact</a>
 </div>
@@ -180,7 +182,9 @@ skillware list
 
 This prints a table of all locally available skills and confirms the install
 and path resolution are working. Running `skillware` with no arguments opens
-the interactive menu.
+the interactive menu. As optional checks you can also run `skillware test` to
+execute bundle tests, and `skillware examples` to browse the runnable example
+index (fetched from GitHub when no local `examples/README.md` is present).
 
 If `skillware` is not recognized, Python's `Scripts` directory may not be on
 your PATH — use `python -m skillware list` as a fallback. See
@@ -292,6 +296,14 @@ Skillware differs from the Model Context Protocol (MCP), and Agent Skills (SKILL
 
 [Read the full comparison here](COMPARISON.md).
 
+## Stats
+
+<a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/badge/Stats-PePyTech-ffdac1?style=flat-square" alt="PePy.tech dashboard"></a>
+<a href="https://pypistats.org/packages/skillware"><img src="https://img.shields.io/badge/Stats-PyPiStats-ffdac1?style=flat-square" alt="PyPI Stats dashboard"></a>
+<a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/pepy/dt/skillware?style=flat-square&label=DLs%20%E2%86%93%20total&color=bbf7d0" alt="Total downloads (PePy)"></a>
+
+PyPI download counts show how often `skillware` is installed from the package index. Numbers come from public third-party aggregators, and they include CI and mirror traffic, so they measure **install activity**, not unique users. Totals may differ slightly between services because each source uses its own window and methodology. Use the stats dashboards in the above badges for charts, version breakdowns, and longer history.
+
 ## Contact
 
 For questions, suggestions, or contributions, please open an issue or reach out to us:

{skillware-0.3.9 → skillware-0.4.0}/README.md

@@ -10,6 +10,7 @@
   <img src="https://img.shields.io/badge/License-MIT-efcefa?style=flat-square" alt="License">
   <img src="https://img.shields.io/badge/Python-3.10+-bae6fd?style=flat-square" alt="Python Version">
   <a href="https://pypi.org/project/skillware/"><img src="https://img.shields.io/pypi/v/skillware?style=flat-square&color=bbf7d0" alt="PyPI Version"></a>
+  <a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/pepy/dt/skillware?style=flat-square&label=DLs%20%E2%86%93&color=ffdac1" alt="Total PyPI downloads"></a>
 </div>
 
 <br/>
@@ -21,6 +22,7 @@
   <a href="#documentation">Documentation</a> •
   <a href="#contributing">Contributing</a> •
   <a href="#comparison">Comparison</a> •
+  <a href="#stats">Stats</a> •
   <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contact">Contact</a>
 </div>
@@ -109,7 +111,9 @@ skillware list
 
 This prints a table of all locally available skills and confirms the install
 and path resolution are working. Running `skillware` with no arguments opens
-the interactive menu.
+the interactive menu. As optional checks you can also run `skillware test` to
+execute bundle tests, and `skillware examples` to browse the runnable example
+index (fetched from GitHub when no local `examples/README.md` is present).
 
 If `skillware` is not recognized, Python's `Scripts` directory may not be on
 your PATH — use `python -m skillware list` as a fallback. See
@@ -221,6 +225,14 @@ Skillware differs from the Model Context Protocol (MCP), and Agent Skills (SKILL
 
 [Read the full comparison here](COMPARISON.md).
 
+## Stats
+
+<a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/badge/Stats-PePyTech-ffdac1?style=flat-square" alt="PePy.tech dashboard"></a>
+<a href="https://pypistats.org/packages/skillware"><img src="https://img.shields.io/badge/Stats-PyPiStats-ffdac1?style=flat-square" alt="PyPI Stats dashboard"></a>
+<a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/pepy/dt/skillware?style=flat-square&label=DLs%20%E2%86%93%20total&color=bbf7d0" alt="Total downloads (PePy)"></a>
+
+PyPI download counts show how often `skillware` is installed from the package index. Numbers come from public third-party aggregators, and they include CI and mirror traffic, so they measure **install activity**, not unique users. Totals may differ slightly between services because each source uses its own window and methodology. Use the stats dashboards in the above badges for charts, version breakdowns, and longer history.
+
 ## Contact
 
 For questions, suggestions, or contributions, please open an issue or reach out to us:

{skillware-0.3.9 → skillware-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.3.9"
+version = "0.4.0"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [

skillware-0.4.0/skills/monitoring/__init__.py

@@ -0,0 +1 @@
+# Monitoring skills package.

skillware-0.4.0/skills/monitoring/token_limiter/__init__.py

@@ -0,0 +1 @@
+# Token hard limit skill package.

skillware-0.4.0/skills/monitoring/token_limiter/budget.py

@@ -0,0 +1,286 @@
+"""Deterministic token budget evaluation for agent loops."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+SCHEMA_VERSION = "1.0"
+DEFAULT_SOFT_THRESHOLD_PCT = 80.0
+VALID_ACTIONS = frozenset({"check", "reset"})
+VALID_DECISIONS = frozenset({"CONTINUE", "WARN", "FORCE_TERMINATE"})
+
+
+def utc_now_iso() -> str:
+    return (
+        datetime.now(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+def load_pricing(data_dir: str) -> Dict[str, Any]:
+    pricing_path = os.path.join(data_dir, "model_pricing.json")
+    with open(pricing_path, "r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _positive_int(value: Any, field: str) -> Tuple[Optional[int], Optional[str]]:
+    if value is None:
+        return None, f"{field} is required."
+    if isinstance(value, bool):
+        return None, f"{field} must be an integer."
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None, f"{field} must be an integer."
+    if parsed < 0:
+        return None, f"{field} must be zero or greater."
+    return parsed, None
+
+
+def _optional_non_negative_int(
+    value: Any, field: str
+) -> Tuple[Optional[int], Optional[str]]:
+    if value is None:
+        return None, None
+    return _positive_int(value, field)
+
+
+def _soft_threshold_pct(value: Any) -> Tuple[float, Optional[str]]:
+    if value is None:
+        return DEFAULT_SOFT_THRESHOLD_PCT, None
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_SOFT_THRESHOLD_PCT, "soft_threshold_pct must be a number."
+    if parsed <= 0 or parsed > 100:
+        return (
+            DEFAULT_SOFT_THRESHOLD_PCT,
+            "soft_threshold_pct must be between 0 and 100.",
+        )
+    return parsed, None
+
+
+def estimate_cost_usd(
+    pricing: Dict[str, Any],
+    model_id: Optional[str],
+    current_token_count: int,
+    input_tokens: Optional[int],
+    output_tokens: Optional[int],
+) -> Tuple[Optional[float], List[str]]:
+    warnings: List[str] = []
+    if not model_id:
+        return None, warnings
+
+    models = pricing.get("models", {})
+    model_key = str(model_id).strip()
+    rates = models.get(model_key)
+
+    if rates is None:
+        fallback = pricing.get("fallback", {})
+        blended = float(fallback.get("blended_usd_per_1m", 5.0))
+        warnings.append(
+            f"Unknown model_id {model_key!r}; using fallback blended rate "
+            f"{blended} USD per 1M tokens."
+        )
+        cost = (current_token_count / 1_000_000.0) * blended
+        return round(cost, 6), warnings
+
+    input_rate = float(rates.get("input_usd_per_1m", 0.0))
+    output_rate = float(rates.get("output_usd_per_1m", 0.0))
+
+    if input_tokens is None and output_tokens is None:
+        input_tokens = current_token_count // 2
+        output_tokens = current_token_count - input_tokens
+        warnings.append(
+            "input_tokens and output_tokens were not provided; "
+            "assuming a 50/50 split for cost estimation."
+        )
+    elif input_tokens is None:
+        input_tokens = max(0, current_token_count - int(output_tokens))
+    elif output_tokens is None:
+        output_tokens = max(0, current_token_count - int(input_tokens))
+
+    cost = (input_tokens / 1_000_000.0) * input_rate + (
+        output_tokens / 1_000_000.0
+    ) * output_rate
+    return round(cost, 6), warnings
+
+
+def build_roi_scaffold(
+    params: Dict[str, Any], cost_usd: Optional[float]
+) -> Dict[str, Any]:
+    roi_value = params.get("roi_value_usd")
+    expected_outcome = params.get("expected_outcome")
+    outcome_delivered = params.get("outcome_delivered")
+
+    scaffold: Dict[str, Any] = {
+        "enabled": False,
+        "status": "not_evaluated",
+        "notes": (
+            "ROI enforcement is not active in v1. Token limits are the sole "
+            "termination trigger. Future versions may compare expected_outcome "
+            "and outcome_delivered against token spend."
+        ),
+    }
+
+    if roi_value is not None or expected_outcome or outcome_delivered is not None:
+        scaffold["enabled"] = True
+        scaffold["roi_value_usd"] = roi_value
+        scaffold["expected_outcome"] = expected_outcome
+        scaffold["outcome_delivered"] = outcome_delivered
+        scaffold["cost_incurred_usd"] = cost_usd
+        scaffold["status"] = "scaffold_only"
+
+    return scaffold
+
+
+def evaluate_budget(
+    params: Dict[str, Any],
+    pricing: Dict[str, Any],
+    turn_cache: Dict[str, Dict[str, Any]],
+) -> Dict[str, Any]:
+    action = (params.get("action") or "check").strip().lower()
+    if action not in VALID_ACTIONS:
+        return {
+            "status": "error",
+            "message": f"Invalid action {action!r}. Expected one of: check, reset.",
+        }
+
+    task_id = (params.get("task_id") or "").strip()
+    if not task_id:
+        return {"status": "error", "message": "task_id is required."}
+
+    if action == "reset":
+        prefix = f"{task_id}|"
+        keys_to_delete = [key for key in turn_cache if key.startswith(prefix)]
+        for key in keys_to_delete:
+            del turn_cache[key]
+        return {
+            "status": "ready",
+            "schema_version": SCHEMA_VERSION,
+            "action": "RESET",
+            "task_id": task_id,
+            "message": f"Cleared {len(keys_to_delete)} cached turn result(s) for task.",
+            "timestamp": utc_now_iso(),
+        }
+
+    current_token_count, err = _positive_int(
+        params.get("current_token_count"), "current_token_count"
+    )
+    if err:
+        return {"status": "error", "message": err}
+
+    max_allowed_tokens, err = _positive_int(
+        params.get("max_allowed_tokens"), "max_allowed_tokens"
+    )
+    if err:
+        return {"status": "error", "message": err}
+
+    if max_allowed_tokens == 0:
+        return {
+            "status": "error",
+            "message": "max_allowed_tokens must be greater than zero.",
+        }
+
+    soft_threshold_pct, soft_err = _soft_threshold_pct(params.get("soft_threshold_pct"))
+    turn_id = (params.get("turn_id") or "").strip()
+    cache_key = f"{task_id}|{turn_id}|{current_token_count}|{max_allowed_tokens}"
+
+    if turn_id and cache_key in turn_cache:
+        cached = dict(turn_cache[cache_key])
+        cached["metadata"] = dict(cached.get("metadata", {}))
+        cached["metadata"]["cache_hit"] = True
+        return cached
+
+    input_tokens, input_err = _optional_non_negative_int(
+        params.get("input_tokens"), "input_tokens"
+    )
+    if input_err:
+        return {"status": "error", "message": input_err}
+
+    output_tokens, output_err = _optional_non_negative_int(
+        params.get("output_tokens"), "output_tokens"
+    )
+    if output_err:
+        return {"status": "error", "message": output_err}
+
+    model_id = (params.get("model_id") or "").strip() or None
+    cost_usd, cost_warnings = estimate_cost_usd(
+        pricing,
+        model_id,
+        current_token_count,
+        input_tokens,
+        output_tokens,
+    )
+
+    utilization_pct = round((current_token_count / max_allowed_tokens) * 100.0, 2)
+    tokens_over_budget = max(0, current_token_count - max_allowed_tokens)
+    soft_limit = int(max_allowed_tokens * (soft_threshold_pct / 100.0))
+
+    warnings: List[str] = []
+    if soft_err:
+        warnings.append(soft_err)
+    warnings.extend(cost_warnings)
+
+    if current_token_count >= max_allowed_tokens:
+        decision = "FORCE_TERMINATE"
+        reason = (
+            f"Token budget exceeded by {tokens_over_budget} "
+            f"({utilization_pct}% of limit)."
+        )
+    elif current_token_count >= soft_limit:
+        decision = "WARN"
+        reason = (
+            f"Token utilization at {utilization_pct}% "
+            f"(soft threshold {soft_threshold_pct}%)."
+        )
+    else:
+        decision = "CONTINUE"
+        reason = (
+            f"Token utilization at {utilization_pct}% "
+            f"({current_token_count}/{max_allowed_tokens})."
+        )
+
+    roi = build_roi_scaffold(params, cost_usd)
+
+    result: Dict[str, Any] = {
+        "status": "ready",
+        "schema_version": SCHEMA_VERSION,
+        "action": decision,
+        "task_id": task_id,
+        "reason": reason,
+        "budget": {
+            "current_token_count": current_token_count,
+            "max_allowed_tokens": max_allowed_tokens,
+            "utilization_pct": utilization_pct,
+            "tokens_over_budget": tokens_over_budget,
+            "soft_threshold_pct": soft_threshold_pct,
+            "soft_limit_tokens": soft_limit,
+        },
+        "cost": {
+            "incurred_usd": cost_usd,
+            "model_id": model_id,
+            "pricing_source": "data/model_pricing.json",
+            "pricing_last_updated": pricing.get("last_updated"),
+        },
+        "roi": roi,
+        "metadata": {
+            "warnings": warnings,
+            "turn_id": turn_id or None,
+            "cache_hit": False,
+            "host_responsibility": (
+                "The host loop must stop when action is FORCE_TERMINATE."
+            ),
+        },
+        "timestamp": utc_now_iso(),
+    }
+
+    if turn_id:
+        turn_cache[cache_key] = dict(result)
+
+    return result

skillware-0.4.0/skills/monitoring/token_limiter/card.json

@@ -0,0 +1,22 @@
+{
+  "name": "Token Limiter",
+  "description": "Budget gate for autonomous agent loops. Returns CONTINUE, WARN, or FORCE_TERMINATE.",
+  "issuer": {
+    "name": "Ross Peili",
+    "email": "vpeilivanidis@gmail.com",
+    "github": "rosspeili",
+    "org": "ARPAHLS"
+  },
+  "icon": "activity",
+  "color": "orange",
+  "ui_schema": {
+    "type": "card",
+    "fields": [
+      {"key": "task_id", "label": "Task"},
+      {"key": "action", "label": "Decision", "type": "status_badge"},
+      {"key": "budget.utilization_pct", "label": "Utilization %", "type": "percent"},
+      {"key": "budget.current_token_count", "label": "Tokens Used", "type": "count"},
+      {"key": "cost.incurred_usd", "label": "Est. Cost (USD)", "type": "currency"}
+    ]
+  }
+}

skillware-0.4.0/skills/monitoring/token_limiter/data/model_pricing.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": "1.0",
+  "last_updated": "2026-05-24",
+  "currency": "USD",
+  "notes": "Indicative public list prices for cost estimates only. Not billing-grade.",
+  "models": {
+    "gpt-4o": {
+      "input_usd_per_1m": 2.5,
+      "output_usd_per_1m": 10.0
+    },
+    "gpt-4o-mini": {
+      "input_usd_per_1m": 0.15,
+      "output_usd_per_1m": 0.6
+    },
+    "claude-3-5-sonnet-latest": {
+      "input_usd_per_1m": 3.0,
+      "output_usd_per_1m": 15.0
+    },
+    "claude-3-5-haiku-latest": {
+      "input_usd_per_1m": 0.8,
+      "output_usd_per_1m": 4.0
+    },
+    "gemini-2.5-flash": {
+      "input_usd_per_1m": 0.15,
+      "output_usd_per_1m": 0.6
+    },
+    "gemini-2.5-flash-lite": {
+      "input_usd_per_1m": 0.075,
+      "output_usd_per_1m": 0.3
+    },
+    "deepseek-chat": {
+      "input_usd_per_1m": 0.27,
+      "output_usd_per_1m": 1.1
+    }
+  },
+  "fallback": {
+    "blended_usd_per_1m": 5.0
+  }
+}

skillware-0.4.0/skills/monitoring/token_limiter/instructions.md

@@ -0,0 +1,42 @@
+# Cognition Instructions: Token Limiter
+
+You have access to the `monitoring/token_limiter` tool.
+
+This skill is a **budget gate** for long-running autonomous loops. It does **not** stop the loop itself. After each model turn (or before the next one), call it with the **cumulative** token count for the task. If the result is `FORCE_TERMINATE`, you must **stop the loop immediately** and report the reason to the operator.
+
+## When to use this skill
+
+- Before starting a high-risk autonomous task (scraping, multi-step research, codegen loops).
+- After **every** model turn in a loop where token spend must stay bounded.
+- When the operator sets a maximum token budget for a task.
+
+## Required host behavior
+
+1. Track `task_id` for the session and pass **cumulative** `current_token_count` (not just the last turn delta unless you maintain the running total yourself).
+2. Set `max_allowed_tokens` from operator policy or task metadata.
+3. On `action: WARN`, consider narrowing scope, compressing context, or asking the operator before continuing.
+4. On `action: FORCE_TERMINATE`, **do not** call the main model again for this task. Return the skill payload to the dashboard or user.
+
+## Parameters
+
+| Field | Required | Notes |
+| :--- | :--- | :--- |
+| `task_id` | Yes | Stable task identifier |
+| `current_token_count` | Yes (check) | Cumulative tokens used so far |
+| `max_allowed_tokens` | Yes (check) | Hard ceiling |
+| `turn_id` | No | Use for idempotent retries of the same turn |
+| `model_id` | No | Enables indicative USD cost in the response |
+| `soft_threshold_pct` | No | Default 80; triggers WARN before hard limit |
+
+## ROI scaffold (v2, not enforced)
+
+Optional fields `roi_value_usd`, `expected_outcome`, and `outcome_delivered` are accepted for future ROI logic. **v1 never terminates on ROI alone.** Token limits are the only termination trigger today.
+
+## Interpreting the response
+
+- `CONTINUE`: Under the soft threshold. Proceed with the next turn.
+- `WARN`: Approaching the limit. Tighten scope or warn the operator.
+- `FORCE_TERMINATE`: Hard limit reached. Stop the loop and surface `reason`.
+- `RESET`: Administrative action clearing cached turn results for a `task_id`.
+
+Cost figures in `cost.incurred_usd` are **indicative** estimates from bundled list prices, not invoice amounts.

skillware-0.4.0/skills/monitoring/token_limiter/manifest.yaml

@@ -0,0 +1,74 @@
+name: "monitoring/token_limiter"
+version: "1.0.0"
+description: "Deterministic token budget gate for autonomous agent loops. Returns CONTINUE, WARN, or FORCE_TERMINATE so the host loop can stop runaway tasks before they exhaust context or budget."
+short_description: "Token budget gate: CONTINUE, WARN, or FORCE_TERMINATE for agent loops."
+issuer:
+  name: Ross Peili
+  email: vpeilivanidis@gmail.com
+  github: rosspeili
+  org: ARPAHLS
+category: "monitoring"
+requirements: []
+parameters:
+  type: object
+  properties:
+    action:
+      type: string
+      description: "Workflow action: check (default) evaluates the budget; reset clears cached turn results for task_id."
+      enum:
+        - check
+        - reset
+    task_id:
+      type: string
+      description: "Stable identifier for the autonomous task or agent session."
+    current_token_count:
+      type: integer
+      description: "Cumulative token count for the task so far. The host loop must track and pass the running total."
+    max_allowed_tokens:
+      type: integer
+      description: "Hard token ceiling for the task. At or above this value the skill returns FORCE_TERMINATE."
+    soft_threshold_pct:
+      type: number
+      description: "Optional warning threshold as a percentage of max_allowed_tokens. Default 80."
+    turn_id:
+      type: string
+      description: "Optional turn identifier for idempotent retries. Same task_id, turn_id, and counts return the cached decision."
+    model_id:
+      type: string
+      description: "Optional model name for indicative USD cost estimates (for example gpt-4o, gemini-2.5-flash)."
+    input_tokens:
+      type: integer
+      description: "Optional input tokens for this turn or cumulative split when estimating cost."
+    output_tokens:
+      type: integer
+      description: "Optional output tokens for this turn or cumulative split when estimating cost."
+    roi_value_usd:
+      type: number
+      description: "Optional scaffold for future ROI checks. Not enforced in v1."
+    expected_outcome:
+      type: string
+      description: "Optional scaffold describing the deliverable expected from the task (v2 ROI)."
+    outcome_delivered:
+      type: boolean
+      description: "Optional scaffold indicating whether the expected outcome was delivered (v2 ROI)."
+  required: []
+outputs:
+  status:
+    type: string
+    description: "ready or error."
+  action:
+    type: string
+    description: "CONTINUE, WARN, FORCE_TERMINATE, or RESET."
+  reason:
+    type: string
+    description: "Human-readable explanation of the decision."
+constitution: |
+  1. INFORMATIONAL ONLY: Output is a budget signal, not billing authority or legal clearance.
+  2. HOST RESPONSIBILITY: The calling loop must stop when action is FORCE_TERMINATE.
+  3. DETERMINISM: Same inputs produce the same decision (except timestamp).
+  4. PRIVACY: Do not accept or store prompt content; only metrics and task identifiers.
+  5. TOKEN FIRST: v1 terminates only on token hard limits. ROI fields are scaffold-only.
+  6. NO SIDE EFFECTS: Do not spawn background tasks, network calls, or process kills.
+presentation:
+  icon: "activity"
+  color: "#E67E22"

skillware-0.4.0/skills/monitoring/token_limiter/skill.py

@@ -0,0 +1,60 @@
+import importlib.util
+import os
+from typing import Any, Dict, Optional
+
+from skillware.core.base_skill import BaseSkill
+
+
+def _import_budget():
+    try:
+        from . import budget as budget_module  # type: ignore[import-not-found]
+    except ImportError:
+        budget_path = os.path.join(os.path.dirname(__file__), "budget.py")
+        spec = importlib.util.spec_from_file_location(
+            "token_limiter_budget", budget_path
+        )
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load budget module from {budget_path}")
+        budget_module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(budget_module)
+    return budget_module
+
+
+_budget = _import_budget()
+evaluate_budget = _budget.evaluate_budget
+load_pricing = _budget.load_pricing
+SCHEMA_VERSION = _budget.SCHEMA_VERSION
+
+
+class TokenLimiterSkill(BaseSkill):
+    """
+    Deterministic token budget gate for autonomous agent loops.
+
+    The skill does not terminate host processes or provider sessions itself.
+    It returns CONTINUE, WARN, or FORCE_TERMINATE and the host loop must act.
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        super().__init__(config)
+        self._data_dir = os.path.join(os.path.dirname(__file__), "data")
+        self._pricing = load_pricing(self._data_dir)
+        self._turn_cache: Dict[str, Dict[str, Any]] = {}
+
+    @property
+    def manifest(self) -> Dict[str, Any]:
+        manifest_path = os.path.join(os.path.dirname(__file__), "manifest.yaml")
+        if os.path.exists(manifest_path):
+            import yaml
+
+            with open(manifest_path, "r", encoding="utf-8") as handle:
+                return yaml.safe_load(handle)
+        return {}
+
+    def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        try:
+            return evaluate_budget(params, self._pricing, self._turn_cache)
+        except Exception as exc:
+            return {
+                "status": "error",
+                "message": f"Token budget evaluation failed: {exc}",
+            }