forge-agent 1.1.5__tar.gz

forge_agent-1.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TREN Studio
+
+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.

forge_agent-1.1.5/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: forge-agent
+Version: 1.1.5
+Summary: The world's most powerful free AI agent. Self-evolving. Zero cost. Forever.
+Author-email: TREN Studio <hello@trenstudio.com>
+License: MIT
+Project-URL: Homepage, https://www.trenstudio.com/FORGE
+Project-URL: Repository, https://github.com/TREN-Studio/FORGE
+Project-URL: Issues, https://github.com/TREN-Studio/FORGE/issues
+Keywords: ai,agent,llm,free,open-source,forge
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2.6
+Requires-Dist: sqlmodel>=0.0.18
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: tenacity>=8.3
+Requires-Dist: diskcache>=5.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: tiktoken>=0.7
+Requires-Dist: colorama>=0.4
+Requires-Dist: cryptography>=42
+Provides-Extra: tools
+Requires-Dist: playwright>=1.44; extra == "tools"
+Requires-Dist: beautifulsoup4>=4.12; extra == "tools"
+Requires-Dist: duckduckgo-search>=6.2; extra == "tools"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# FORGE
+
+**Free Open Reasoning and Generation Engine**
+
+FORGE is an English-first, multilingual AI operator that routes across free and local models, chooses the best execution path for the task, and runs through a modular skill system built for real-world work.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-orange.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-orange.svg)](https://python.org)
+[![Website](https://img.shields.io/badge/website-trenstudio.com%2FFORGE-orange.svg)](https://www.trenstudio.com/FORGE)
+
+## Why FORGE
+
+- English-first product surface with multilingual task support.
+- Smart model routing across free providers and local runtimes.
+- Skill-based execution brain with planning, safety, validation, and recovery.
+- Persistent context and memory for long-running operator workflows.
+- Safe artifact generation for reports, analysis outputs, and execution traces.
+
+## Core Capabilities
+
+### Universal Model Routing
+
+FORGE connects to multiple providers and local runtimes, scores candidates for the active task, and selects the strongest available path.
+
+### Skill-Based Operator Brain
+
+The operator is split into explicit layers:
+
+1. Intent resolution
+2. Structured planning
+3. Skill routing
+4. Safety guard
+5. Execution runtime
+6. Validation
+7. Recovery and fallback
+8. Response composition
+
+### Grounded Local Execution
+
+FORGE can inspect a workspace, read files safely, analyze the codebase with evidence, and write output artifacts without mutating source files.
+
+## Architecture
+
+```text
+forge/
+  brain/         Core orchestration brain
+  core/          Provider routing, quotas, discovery, session runtime
+  memory/        Session and persistent context
+  providers/     Provider adapters
+  recovery/      Retry and fallback handling
+  safety/        Risk policy and confirmation logic
+  skills/        Skill contracts, registry, loader, router, runtime
+  skills_catalog/Pluggable skill folders
+  tools/         Safe local execution tools
+  validation/    Output and completion validation
+```
+
+## Skill System
+
+Every skill is self-contained in its own folder:
+
+```text
+skills_catalog/<skill-name>/
+  SKILL.md
+  schema.json        # optional
+  executor.py        # optional
+```
+
+This makes new skills pluggable without rewriting the core brain.
+
+## Install
+
+```bash
+pip install forge-agent
+forge --version
+```
+
+## Quick Start
+
+```bash
+forge --version
+forge status
+forge discover
+forge operate "Analyze this repository and save a summary file"
+forge operate "Read forge/brain/operator.py and explain the execution flow"
+```
+
+Current Python package target: `1.1.5`.
+
+## Python API
+
+```python
+import forge
+
+result = forge.operate("Analyze this project and save a summary file")
+print(result.result)
+```
+
+## Safety Model
+
+- Untrusted external skills do not run automatically.
+- Medium-risk actions can be forced into dry-run mode.
+- High-risk actions require confirmation.
+- Validation runs before success is reported.
+- FORGE never claims execution without evidence.
+
+## Status
+
+Current foundation includes:
+
+- model routing and provider registry
+- quota management and model discovery
+- skill registry and skill router
+- skill governance metadata, precondition checks, and gated Tier 4 routing
+- live desktop execution streaming with visible plan and step progress
+- safety, validation, and recovery layers
+- grounded workspace analysis and file reading skills
+
+## Windows Releases
+
+- Current public release line: `1.1.4`.
+- GitHub's latest stable release must also resolve to `v1.1.4`; prerelease engineering snapshots such as `v1.1.5-AgentReality` are not canonical install releases.
+- The canonical public download source is the GitHub Release for the matching tag: https://github.com/TREN-Studio/FORGE/releases/tag/v1.1.4
+- The release workflow in `.github/workflows/release_forge_windows.yml` builds `FORGE-Desktop.exe`, `FORGE-Setup-<version>.exe`, the portable ZIP, the source ZIP, `SHA256SUMS-<version>.txt`, and `release-manifest.json` from one pipeline.
+- That same pipeline publishes the assets to GitHub Release and mirrors the exact same bytes to `https://www.trenstudio.com/FORGE/downloads/` when Hostinger secrets are configured.
+- The supported desktop build entrypoint is `python tools/build_windows_desktop.py`; that script is the source of truth for orchestration and invokes the portable `FORGE-Desktop.spec`.
+- Release packaging runs through `python tools/package_release_assets.py`, which writes release assets under `release-assets/` only. It does not publish or sync binary files into `site/downloads/`.
+- The public downloads page at `site/downloads/index.html` reads `release-manifest.json`, generated from the canonical GitHub Release or from the release pipeline, and prefers verified official-site mirror URLs while preserving GitHub URLs as the canonical reference.
+- `python tools/verify_release_public_assets.py --manifest release-assets/release-manifest.json --require-mirror` verifies version, size, SHA256, GitHub Release presence, and byte identity for the Hostinger mirror.
+- `tools/deploy_hostinger_site.py` deploys the downloads page and portal only; the TREN Studio root page owns `https://www.trenstudio.com/FORGE/`, and the release workflow owns `release-manifest.json` plus mirrored binary files on Hostinger.
+- Legacy desktop spec variants were removed. `FORGE-Desktop.spec` is the only supported PyInstaller spec.
+- If `WINDOWS_PFX_BASE64` and `WINDOWS_PFX_PASSWORD` are configured in GitHub Secrets, the workflow signs both artifacts before publishing the GitHub Release.
+- Until code signing is configured, Windows SmartScreen and local execution reputation checks can still block downloaded installers.
+
+## Roadmap
+
+1. Add guarded file editing and patch execution
+2. Add web research and publishing skills
+3. Add audit logs and evidence snapshots for every action
+4. Add richer test coverage and benchmark suites
+
+## Contributing
+
+FORGE is designed as an open-source operator platform. Contributions should preserve:
+
+- modular contracts
+- safety-by-default behavior
+- grounded execution
+- production-oriented output quality
+
+## License
+
+MIT
+
+## Links
+
+- Website: https://www.trenstudio.com/FORGE
+- Downloads: https://www.trenstudio.com/FORGE/downloads/
+- Organization: https://github.com/TREN-Studio
+- Repository: https://github.com/TREN-Studio/FORGE
+
+## Production Deployment
+
+FORGE keeps its public downloads page and portal bundle inside [`site/`](site). The production page at `https://www.trenstudio.com/FORGE/` remains the TREN Studio project page; the FORGE download interface lives at `https://www.trenstudio.com/FORGE/downloads/` and is deployed from `site/downloads/index.html`.
+
+GitHub Release is the canonical release record. Hostinger may serve an official mirror under `https://www.trenstudio.com/FORGE/downloads/`, but only when the files are copied from the same CI-built release assets and pass SHA256, file size, version, and byte-identity verification.
+
+The current public download set is:
+
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Desktop.exe`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Setup-1.1.4.exe`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Windows-Portable-1.1.4.zip`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Source-v1.1.4.zip`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/SHA256SUMS-1.1.4.txt`
+
+The matching official-site mirror paths, when present, are:
+
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Desktop.exe`
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Setup-1.1.4.exe`
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Windows-Portable-1.1.4.zip`
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Source-v1.1.4.zip`
+- `https://www.trenstudio.com/FORGE/downloads/SHA256SUMS-1.1.4.txt`
+
+### Auto-Deploy Pipeline
+
+GitHub Actions workflow: [`.github/workflows/deploy_forge_site.yml`](.github/workflows/deploy_forge_site.yml)
+
+Deployment script: [`tools/deploy_hostinger_site.py`](tools/deploy_hostinger_site.py). It preserves the remote `/FORGE/index.html` root page unless this repository explicitly adds a root `site/index.html`.
+
+Deploy guard: the script refuses to deploy `site/index.html` to `/FORGE/index.html` unless `--allow-root-index-deploy` or `FORGE_ALLOW_ROOT_INDEX_DEPLOY=1` is provided. Normal downloads/portal deploys also compare the remote `/FORGE/index.html` hash before and after upload and fail if it changes.
+
+Route verification: [`tools/verify_forge_public_routes.py`](tools/verify_forge_public_routes.py) checks that `/FORGE/` is still the original project page, `/FORGE/downloads/` is still the downloads page, and the public `release-manifest.json` matches the expected release manifest.
+
+Required GitHub repository secrets:
+
+- `HOSTINGER_HOST`
+- `HOSTINGER_PORT`
+- `HOSTINGER_USERNAME`
+- `HOSTINGER_PASSWORD`
+- `HOSTINGER_REMOTE_ROOT`
+
+Recommended `HOSTINGER_REMOTE_ROOT` value:
+
+```text
+domains/trenstudio.com/public_html/FORGE
+```
+
+Manual local deploy remains available:
+
+```bash
+python tools/deploy_hostinger_site.py
+```

forge_agent-1.1.5/README.md

@@ -0,0 +1,212 @@
+# FORGE
+
+**Free Open Reasoning and Generation Engine**
+
+FORGE is an English-first, multilingual AI operator that routes across free and local models, chooses the best execution path for the task, and runs through a modular skill system built for real-world work.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-orange.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-orange.svg)](https://python.org)
+[![Website](https://img.shields.io/badge/website-trenstudio.com%2FFORGE-orange.svg)](https://www.trenstudio.com/FORGE)
+
+## Why FORGE
+
+- English-first product surface with multilingual task support.
+- Smart model routing across free providers and local runtimes.
+- Skill-based execution brain with planning, safety, validation, and recovery.
+- Persistent context and memory for long-running operator workflows.
+- Safe artifact generation for reports, analysis outputs, and execution traces.
+
+## Core Capabilities
+
+### Universal Model Routing
+
+FORGE connects to multiple providers and local runtimes, scores candidates for the active task, and selects the strongest available path.
+
+### Skill-Based Operator Brain
+
+The operator is split into explicit layers:
+
+1. Intent resolution
+2. Structured planning
+3. Skill routing
+4. Safety guard
+5. Execution runtime
+6. Validation
+7. Recovery and fallback
+8. Response composition
+
+### Grounded Local Execution
+
+FORGE can inspect a workspace, read files safely, analyze the codebase with evidence, and write output artifacts without mutating source files.
+
+## Architecture
+
+```text
+forge/
+  brain/         Core orchestration brain
+  core/          Provider routing, quotas, discovery, session runtime
+  memory/        Session and persistent context
+  providers/     Provider adapters
+  recovery/      Retry and fallback handling
+  safety/        Risk policy and confirmation logic
+  skills/        Skill contracts, registry, loader, router, runtime
+  skills_catalog/Pluggable skill folders
+  tools/         Safe local execution tools
+  validation/    Output and completion validation
+```
+
+## Skill System
+
+Every skill is self-contained in its own folder:
+
+```text
+skills_catalog/<skill-name>/
+  SKILL.md
+  schema.json        # optional
+  executor.py        # optional
+```
+
+This makes new skills pluggable without rewriting the core brain.
+
+## Install
+
+```bash
+pip install forge-agent
+forge --version
+```
+
+## Quick Start
+
+```bash
+forge --version
+forge status
+forge discover
+forge operate "Analyze this repository and save a summary file"
+forge operate "Read forge/brain/operator.py and explain the execution flow"
+```
+
+Current Python package target: `1.1.5`.
+
+## Python API
+
+```python
+import forge
+
+result = forge.operate("Analyze this project and save a summary file")
+print(result.result)
+```
+
+## Safety Model
+
+- Untrusted external skills do not run automatically.
+- Medium-risk actions can be forced into dry-run mode.
+- High-risk actions require confirmation.
+- Validation runs before success is reported.
+- FORGE never claims execution without evidence.
+
+## Status
+
+Current foundation includes:
+
+- model routing and provider registry
+- quota management and model discovery
+- skill registry and skill router
+- skill governance metadata, precondition checks, and gated Tier 4 routing
+- live desktop execution streaming with visible plan and step progress
+- safety, validation, and recovery layers
+- grounded workspace analysis and file reading skills
+
+## Windows Releases
+
+- Current public release line: `1.1.4`.
+- GitHub's latest stable release must also resolve to `v1.1.4`; prerelease engineering snapshots such as `v1.1.5-AgentReality` are not canonical install releases.
+- The canonical public download source is the GitHub Release for the matching tag: https://github.com/TREN-Studio/FORGE/releases/tag/v1.1.4
+- The release workflow in `.github/workflows/release_forge_windows.yml` builds `FORGE-Desktop.exe`, `FORGE-Setup-<version>.exe`, the portable ZIP, the source ZIP, `SHA256SUMS-<version>.txt`, and `release-manifest.json` from one pipeline.
+- That same pipeline publishes the assets to GitHub Release and mirrors the exact same bytes to `https://www.trenstudio.com/FORGE/downloads/` when Hostinger secrets are configured.
+- The supported desktop build entrypoint is `python tools/build_windows_desktop.py`; that script is the source of truth for orchestration and invokes the portable `FORGE-Desktop.spec`.
+- Release packaging runs through `python tools/package_release_assets.py`, which writes release assets under `release-assets/` only. It does not publish or sync binary files into `site/downloads/`.
+- The public downloads page at `site/downloads/index.html` reads `release-manifest.json`, generated from the canonical GitHub Release or from the release pipeline, and prefers verified official-site mirror URLs while preserving GitHub URLs as the canonical reference.
+- `python tools/verify_release_public_assets.py --manifest release-assets/release-manifest.json --require-mirror` verifies version, size, SHA256, GitHub Release presence, and byte identity for the Hostinger mirror.
+- `tools/deploy_hostinger_site.py` deploys the downloads page and portal only; the TREN Studio root page owns `https://www.trenstudio.com/FORGE/`, and the release workflow owns `release-manifest.json` plus mirrored binary files on Hostinger.
+- Legacy desktop spec variants were removed. `FORGE-Desktop.spec` is the only supported PyInstaller spec.
+- If `WINDOWS_PFX_BASE64` and `WINDOWS_PFX_PASSWORD` are configured in GitHub Secrets, the workflow signs both artifacts before publishing the GitHub Release.
+- Until code signing is configured, Windows SmartScreen and local execution reputation checks can still block downloaded installers.
+
+## Roadmap
+
+1. Add guarded file editing and patch execution
+2. Add web research and publishing skills
+3. Add audit logs and evidence snapshots for every action
+4. Add richer test coverage and benchmark suites
+
+## Contributing
+
+FORGE is designed as an open-source operator platform. Contributions should preserve:
+
+- modular contracts
+- safety-by-default behavior
+- grounded execution
+- production-oriented output quality
+
+## License
+
+MIT
+
+## Links
+
+- Website: https://www.trenstudio.com/FORGE
+- Downloads: https://www.trenstudio.com/FORGE/downloads/
+- Organization: https://github.com/TREN-Studio
+- Repository: https://github.com/TREN-Studio/FORGE
+
+## Production Deployment
+
+FORGE keeps its public downloads page and portal bundle inside [`site/`](site). The production page at `https://www.trenstudio.com/FORGE/` remains the TREN Studio project page; the FORGE download interface lives at `https://www.trenstudio.com/FORGE/downloads/` and is deployed from `site/downloads/index.html`.
+
+GitHub Release is the canonical release record. Hostinger may serve an official mirror under `https://www.trenstudio.com/FORGE/downloads/`, but only when the files are copied from the same CI-built release assets and pass SHA256, file size, version, and byte-identity verification.
+
+The current public download set is:
+
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Desktop.exe`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Setup-1.1.4.exe`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Windows-Portable-1.1.4.zip`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/FORGE-Source-v1.1.4.zip`
+- `https://github.com/TREN-Studio/FORGE/releases/download/v1.1.4/SHA256SUMS-1.1.4.txt`
+
+The matching official-site mirror paths, when present, are:
+
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Desktop.exe`
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Setup-1.1.4.exe`
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Windows-Portable-1.1.4.zip`
+- `https://www.trenstudio.com/FORGE/downloads/FORGE-Source-v1.1.4.zip`
+- `https://www.trenstudio.com/FORGE/downloads/SHA256SUMS-1.1.4.txt`
+
+### Auto-Deploy Pipeline
+
+GitHub Actions workflow: [`.github/workflows/deploy_forge_site.yml`](.github/workflows/deploy_forge_site.yml)
+
+Deployment script: [`tools/deploy_hostinger_site.py`](tools/deploy_hostinger_site.py). It preserves the remote `/FORGE/index.html` root page unless this repository explicitly adds a root `site/index.html`.
+
+Deploy guard: the script refuses to deploy `site/index.html` to `/FORGE/index.html` unless `--allow-root-index-deploy` or `FORGE_ALLOW_ROOT_INDEX_DEPLOY=1` is provided. Normal downloads/portal deploys also compare the remote `/FORGE/index.html` hash before and after upload and fail if it changes.
+
+Route verification: [`tools/verify_forge_public_routes.py`](tools/verify_forge_public_routes.py) checks that `/FORGE/` is still the original project page, `/FORGE/downloads/` is still the downloads page, and the public `release-manifest.json` matches the expected release manifest.
+
+Required GitHub repository secrets:
+
+- `HOSTINGER_HOST`
+- `HOSTINGER_PORT`
+- `HOSTINGER_USERNAME`
+- `HOSTINGER_PASSWORD`
+- `HOSTINGER_REMOTE_ROOT`
+
+Recommended `HOSTINGER_REMOTE_ROOT` value:
+
+```text
+domains/trenstudio.com/public_html/FORGE
+```
+
+Manual local deploy remains available:
+
+```bash
+python tools/deploy_hostinger_site.py
+```

forge_agent-1.1.5/forge/__init__.py

@@ -0,0 +1,63 @@
+"""
+FORGE — Free Open Reasoning & Generation Engine
+================================================
+The world's most powerful free AI agent.
+Self-evolving. Zero cost. Forever.
+
+  forge.ask("write me a web scraper")     # auto-selects best free model
+  forge.code("fix this bug", file="x.py") # routes to coding specialist
+  forge.research("quantum computing")     # deep multi-model research
+
+GitHub : https://github.com/trenstudio/forge
+Website: https://www.trenstudio.com/FORGE
+License: MIT
+"""
+
+__version__ = "1.1.5"
+__author__  = "TREN Studio"
+__license__ = "MIT"
+
+from forge.core.router   import ForgeRouter
+from forge.core.session  import ForgeSession
+from forge.brain.operator import ForgeOperator
+from forge.memory.graph  import MemoryGraph
+from forge.runtime import ForgeAgentRuntime
+
+# One-line convenience API
+_default_session: ForgeSession | None = None
+
+def _session() -> ForgeSession:
+    global _default_session
+    if _default_session is None:
+        _default_session = ForgeSession()
+    return _default_session
+
+def ask(prompt: str, **kwargs) -> str:
+    """Send a prompt. FORGE picks the best free model automatically."""
+    return _session().ask(prompt, **kwargs)
+
+def code(prompt: str, **kwargs) -> str:
+    """Coding task — routed to the strongest available coding model."""
+    return _session().ask(prompt, task_type="code", **kwargs)
+
+def research(prompt: str, **kwargs) -> str:
+    """Deep research task with optional web search."""
+    return _session().ask(prompt, task_type="research", **kwargs)
+
+def operate(prompt: str, **kwargs) -> str:
+    """Run the skill-based operator brain."""
+    operator = ForgeOperator()
+    return operator.handle_as_text(prompt, **kwargs)
+
+__all__ = [
+    "__version__",
+    "ForgeRouter",
+    "ForgeSession",
+    "ForgeOperator",
+    "ForgeAgentRuntime",
+    "MemoryGraph",
+    "ask",
+    "code",
+    "operate",
+    "research",
+]

forge_agent-1.1.5/forge/brain/__init__.py

@@ -0,0 +1,4 @@
+from forge.brain.prompt import CORE_BRAIN_PROMPT
+from forge.brain.operator import ForgeOperator
+
+__all__ = ["CORE_BRAIN_PROMPT", "ForgeOperator"]

forge_agent-1.1.5/forge/brain/approval.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from forge.runtime.state_store import PersistentStateStore
+
+
+AUTO_APPROVE_CLASSES = {"local_readonly"}
+HUMAN_APPROVAL_CLASSES = {
+    "network_post",
+    "network_egress",
+    "authenticated_browser",
+    "external_publish",
+    "sensitive_file_write",
+    "destructive_shell",
+}
+
+
+@dataclass(slots=True)
+class ApprovalDecision:
+    allowed: bool
+    approval_required: bool
+    approval_id: str | None
+    approval_class: str | None
+    notes: list[str]
+    status: str
+
+
+class ApprovalPolicyEngine:
+    """Policy + encrypted payload approval flow."""
+
+    def __init__(self, store: PersistentStateStore) -> None:
+        self._store = store
+
+    def evaluate(
+        self,
+        *,
+        mission_id: str,
+        step_id: str,
+        approval_class: str | None,
+        request_excerpt: str,
+        payload: dict[str, Any],
+        summary: str,
+        confirmed: bool,
+    ) -> ApprovalDecision:
+        if not approval_class:
+            return ApprovalDecision(True, False, None, None, [], "allowed")
+
+        if approval_class in AUTO_APPROVE_CLASSES:
+            return ApprovalDecision(
+                True,
+                False,
+                None,
+                approval_class,
+                [f"Approval class `{approval_class}` auto-approved by policy."],
+                "auto_approved",
+            )
+
+        if confirmed:
+            return ApprovalDecision(
+                True,
+                False,
+                None,
+                approval_class,
+                [f"Approval class `{approval_class}` approved explicitly by operator input."],
+                "confirmed",
+            )
+
+        if approval_class in HUMAN_APPROVAL_CLASSES:
+            approval_id = self._store.create_pending_approval(
+                mission_id=mission_id,
+                step_id=step_id,
+                approval_class=approval_class,
+                request_excerpt=request_excerpt[:500],
+                payload=payload,
+                summary=summary,
+                policy_mode="human_approval",
+            )
+            return ApprovalDecision(
+                False,
+                True,
+                approval_id,
+                approval_class,
+                [
+                    f"Approval class: {approval_class}. Human confirmation is required before execution.",
+                    f"Approval request created: {approval_id}.",
+                ],
+                "pending",
+            )
+
+        return ApprovalDecision(
+            True,
+            False,
+            None,
+            approval_class,
+            [f"Approval class `{approval_class}` allowed by current policy."],
+            "allowed",
+        )
+
+    def approval_status(self, approval_id: str) -> dict[str, Any] | None:
+        return self._store.get_approval(approval_id, include_payload=False)
+
+    def approve(self, approval_id: str, *, notes: str = "") -> dict[str, Any] | None:
+        return self._store.decide_approval(approval_id, approved=True, notes=notes)
+
+    def reject(self, approval_id: str, *, notes: str = "") -> dict[str, Any] | None:
+        return self._store.decide_approval(approval_id, approved=False, notes=notes)
+
+    def list_pending(self) -> list[dict[str, Any]]:
+        return self._store.list_approvals(status="pending")