foresight-agent-guard 0.1.0__py3-none-any.whl

foresight/__init__.py

@@ -0,0 +1,3 @@
+"""Foresight predictive routing and session-monitoring package."""
+
+__version__ = "0.1.0"

foresight/benchmark.py

@@ -0,0 +1,153 @@
+"""Deterministic, hand-authored evaluation set for Foresight tier prediction.
+
+Run this module deliberately: it makes one real GPT-5.6-terra prediction per
+case and writes the measured outputs to ``benchmark_results.json``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Literal
+
+from dotenv import load_dotenv
+from openai import OpenAI
+from rich.console import Console
+from rich.table import Table
+
+from foresight.predictor import PREDICTION_SCHEMA, SYSTEM_PROMPT, predict_complexity
+from sentry.eventbus.server import create_cost_tracker
+from sentry.policy.engine import TERRA_MODEL
+
+
+Tier = Literal["luna", "terra", "sol"]
+RESULT_PATH = Path("benchmark_results.json")
+
+# This fixed corpus is intentionally hand-authored rather than sampled at run
+# time, so reported score changes come from model behavior, not a moving set.
+BENCHMARK_CASES: list[dict[str, str]] = [
+    {"task": "Rename a local variable in ./src/utils/format_date.py for clarity.", "expected_tier": "luna", "expected_blast_radius": "isolated"},
+    {"task": "Format ./src/components/Button.tsx with the existing project formatter.", "expected_tier": "luna", "expected_blast_radius": "isolated"},
+    {"task": "Fix a typo in one validation error string in ./src/forms/login.py.", "expected_tier": "luna", "expected_blast_radius": "isolated"},
+    {"task": "Add a missing null check to the single function in ./src/utils/parse_query.py.", "expected_tier": "luna", "expected_blast_radius": "isolated"},
+    {"task": "Update a CSS spacing value in ./src/styles/header.css to match the design token.", "expected_tier": "luna", "expected_blast_radius": "isolated"},
+    {"task": "Add a profile avatar upload feature across the existing profile form, API route, and validation tests.", "expected_tier": "terra", "expected_blast_radius": "moderate"},
+    {"task": "Fix pagination state resetting when filters change in the search page and its related hooks.", "expected_tier": "terra", "expected_blast_radius": "moderate"},
+    {"task": "Add CSV export to the reports page using the existing reporting API and tests.", "expected_tier": "terra", "expected_blast_radius": "moderate"},
+    {"task": "Implement a scoped notification preference toggle in settings, including the API handler and unit tests.", "expected_tier": "terra", "expected_blast_radius": "moderate"},
+    {"task": "Repair a bug where the checkout summary shows stale shipping totals after an address update.", "expected_tier": "terra", "expected_blast_radius": "moderate"},
+    {"task": "Refactor the authentication flow to add multi-factor authentication with recovery codes.", "expected_tier": "sol", "expected_blast_radius": "wide"},
+    {"task": "Migrate payment processing from the legacy provider API to its current version without interrupting subscriptions.", "expected_tier": "sol", "expected_blast_radius": "wide"},
+    {"task": "Design and implement role-based authorization across the admin API, UI, and audit logging.", "expected_tier": "sol", "expected_blast_radius": "wide"},
+    {"task": "Plan and execute a database migration that splits the orders table while preserving historical reporting.", "expected_tier": "sol", "expected_blast_radius": "wide"},
+    {"task": "Replace the session management architecture to support SSO, token rotation, and account recovery.", "expected_tier": "sol", "expected_blast_radius": "wide"},
+]
+
+_TIER_ORDER: dict[str, int] = {"luna": 0, "terra": 1, "sol": 2}
+
+
+def _category(expected: Tier, actual: Tier) -> str:
+    """Classify an exact prediction or its safety direction."""
+
+    if actual == expected:
+        return "correct"
+    return "conservative" if _TIER_ORDER[actual] > _TIER_ORDER[expected] else "risky"
+
+
+def run_benchmark() -> dict[str, Any]:
+    """Run every fixed case once, render results, and export evidence JSON."""
+
+    load_dotenv()
+    console = Console()
+    tracker = create_cost_tracker()
+    results: list[dict[str, Any]] = []
+    for case in BENCHMARK_CASES:
+        event_count = len(tracker.events)
+        prediction = predict_complexity(case["task"], tracker)
+        call_cost = sum(event.cost_usd for event in tracker.events[event_count:])
+        expected_tier = case["expected_tier"]
+        predicted_tier = prediction["predicted_tier"]
+        results.append({**case, "prediction": prediction, "result_category": _category(expected_tier, predicted_tier), "cost_usd": call_cost})
+
+    counts = {name: sum(row["result_category"] == name for row in results) for name in ("correct", "conservative", "risky")}
+    exported = {"case_count": len(BENCHMARK_CASES), "results": results, "aggregate": {**counts, "total_cost_usd": tracker.get_running_total(), "cost_events": [asdict(event) for event in tracker.events]}}
+    RESULT_PATH.write_text(json.dumps(exported, indent=2), encoding="utf-8")
+    _render(console, results, counts, tracker.get_running_total())
+    console.print(f"[dim]Evidence exported to {RESULT_PATH}[/dim]")
+    return exported
+
+
+def capture_response_id() -> dict[str, Any]:
+    """Make one minimal real prediction and persist its OpenAI response ID.
+
+    This is separate from the 15-case corpus so the attestation can be refreshed
+    without paying for a complete benchmark rerun.
+    """
+
+    load_dotenv()
+    tracker = create_cost_tracker()
+    task = "Rename one local variable in ./src/utils/format_date.py for clarity."
+    response = OpenAI().responses.create(
+        model=TERRA_MODEL,
+        reasoning={"effort": "medium"},
+        max_output_tokens=120,
+        prompt_cache_key="foresight-predictor-v1",
+        input=[{"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": task}],
+        text={
+            "format": {
+                "type": "json_schema",
+                "name": "foresight_prediction",
+                "schema": PREDICTION_SCHEMA,
+                "strict": True,
+            }
+        },
+    )
+    cost = tracker.record_response(TERRA_MODEL, response)
+    response_id = getattr(response, "id", None)
+    if not isinstance(response_id, str):
+        raise ValueError("OpenAI response did not include a response ID")
+    evidence = json.loads(RESULT_PATH.read_text(encoding="utf-8"))
+    captured = {
+        "response_id": response_id,
+        "model": TERRA_MODEL,
+        "task": task,
+        "prediction": json.loads(response.output_text),
+        "cost_usd": cost.cost_usd,
+    }
+    evidence["tamper_evident_response"] = captured
+    RESULT_PATH.write_text(json.dumps(evidence, indent=2), encoding="utf-8")
+    return captured
+
+
+def _render(console: Console, results: list[dict[str, Any]], counts: dict[str, int], total_cost: float) -> None:
+    """Render a compact, readable summary of the measured benchmark."""
+
+    table = Table(title="Foresight tier-prediction benchmark")
+    table.add_column("Task", max_width=52)
+    table.add_column("Expected", justify="center")
+    table.add_column("Predicted", justify="center")
+    table.add_column("Expected radius", justify="center")
+    table.add_column("Predicted radius", justify="center")
+    table.add_column("Result", justify="center")
+    table.add_column("Cost", justify="right")
+    styles = {"correct": "green", "conservative": "yellow", "risky": "red bold"}
+    for row in results:
+        prediction = row["prediction"]
+        category = row["result_category"]
+        table.add_row(row["task"], row["expected_tier"], prediction["predicted_tier"], row["expected_blast_radius"], prediction["estimated_blast_radius"], f"[{styles[category]}]{category}[/{styles[category]}]", f"${row['cost_usd']:.4f}")
+    console.print(table)
+    console.print(f"[bold]{counts['correct']}/{len(results)} exact match, {counts['conservative']} conservative, [red]{counts['risky']} risky (0 is the target for risky)[/red][/bold]")
+    console.print(f"Total benchmark cost: [cyan]${total_cost:.4f}[/cyan]")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Run or attest the Foresight tier benchmark.")
+    parser.add_argument("--capture-response-id", action="store_true", help="Make one minimal call and store its response ID.")
+    arguments = parser.parse_args()
+    if arguments.capture_response_id:
+        print(json.dumps(capture_response_id(), indent=2))
+    else:
+        run_benchmark()

foresight/cli.py

@@ -0,0 +1,370 @@
+"""Rich command-line interface for Foresight session setup and monitoring."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import subprocess
+import threading
+import uuid
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+import click
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from foresight.config import ForesightConfig, load_config, write_default_config
+from foresight.predictor import Phase, WorkflowPlan, generate_workflow_plan, predict_complexity
+from foresight.session_monitor import SessionMonitor
+from sentry.eventbus.server import (
+    broadcast_signal,
+    create_cost_tracker,
+    create_sentry_proxy,
+    export_audit_log,
+    start_server,
+)
+from sentry.policy.engine import evaluate_action, scope_to_policy
+from sentry.policy.schema import Policy
+from sentry.proxy.interceptor import SentryBlockedException
+
+VERSION = "0.1.0"
+ACCENT = "cyan"
+STATE = Path(".foresight")
+console = Console()
+
+COMMANDS = (
+    ("init", "Infer a narrow policy and a predicted task tier."),
+    ("run -- <command>", "Run a command under Foresight and Sentry monitoring."),
+    ("status", "Show the most recent saved session report."),
+    ("export [--session ID]", "Export the current in-memory audit log as JSON."),
+    ("config init|show", "Create or inspect editable Foresight defaults."),
+)
+
+
+def _server(config: ForesightConfig) -> None:
+    """Run the local WebSocket event bus in a daemon thread."""
+
+    asyncio.run(start_server(config.eventbus_host, config.eventbus_port))
+
+
+def _print_banner() -> None:
+    """Render the shared Foresight entry banner."""
+
+    orb = r"""
+      .-------.
+     /  .-.    \
+    |  ( o )    |
+    |    ^       |
+     \  /_\     /
+      `-._.-'"""
+    details = Text.from_markup(
+        f"[bold {ACCENT}]FORESIGHT[/bold {ACCENT}]  [dim]v{VERSION}[/dim]\n\n"
+        "Predictive cost & tier routing for\n"
+        "AI coding agents\n\n"
+        "[dim]Model:[/dim] gpt-5.6-terra\n"
+        f"[dim]Session:[/dim] {Path.cwd()}"
+    )
+    content = Table.grid(padding=(0, 3))
+    content.add_column(no_wrap=True)
+    content.add_column()
+    content.add_row(Text(orb, style=f"bold {ACCENT}"), details)
+    console.print(
+        Panel(
+            content,
+            border_style=ACCENT,
+            box=box.ROUNDED,
+            padding=(1, 3),
+            expand=False,
+        )
+    )
+
+
+def _print_header(title: str, detail: str) -> None:
+    """Render the compact, consistent command header."""
+
+    console.print(f"[bold {ACCENT}]>>[/bold {ACCENT}] [bold]{title}[/bold] [dim]{detail}[/dim]")
+
+
+def _print_command_table() -> None:
+    """Render the command reference used by bare invocation and --help."""
+
+    table = Table(box=box.SIMPLE_HEAVY, show_header=True, header_style=f"bold {ACCENT}")
+    table.add_column("COMMAND", style=f"bold {ACCENT}", no_wrap=True)
+    table.add_column("DESCRIPTION", style="white")
+    for command, description in COMMANDS:
+        table.add_row(command, description)
+    console.print(table)
+    console.print("[dim]Use `foresight <command> --help` for command-specific options.[/dim]")
+
+
+def _show_help(context: click.Context, parameter: click.Parameter, value: bool) -> None:
+    """Replace Click's plain help screen with the Rich command reference."""
+
+    if not value or context.resilient_parsing:
+        return
+    _print_banner()
+    _print_command_table()
+    context.exit()
+
+
+def _load() -> tuple[Policy, dict[str, Any], WorkflowPlan | None]:
+    """Load the saved policy and prediction for a monitored run."""
+
+    policy_path = STATE / "policy.json"
+    prediction_path = STATE / "prediction.json"
+    if not policy_path.exists() or not prediction_path.exists():
+        raise click.ClickException("No session config. Run `foresight init` first.")
+    workflow_path = STATE / "workflow_plan.json"
+    workflow_plan = None
+    if workflow_path.exists():
+        workflow_data = json.loads(workflow_path.read_text(encoding="utf-8"))
+        workflow_plan = WorkflowPlan(
+            phases=[Phase(**phase) for phase in workflow_data["phases"]],
+            predicted_tier=workflow_data["predicted_tier"],
+            predicted_effort=workflow_data["predicted_effort"],
+            generated_stop_prompt=workflow_data["generated_stop_prompt"],
+        )
+    return (
+        Policy(**json.loads(policy_path.read_text(encoding="utf-8"))),
+        json.loads(prediction_path.read_text(encoding="utf-8")),
+        workflow_plan,
+    )
+
+
+def _print_workflow_plan(plan: WorkflowPlan) -> None:
+    """Render an optional typed plan and its copy-paste stop prompt."""
+
+    table = Table(title="Bounded workflow plan", box=box.ROUNDED, border_style=ACCENT)
+    table.add_column("Phase", style=f"bold {ACCENT}")
+    table.add_column("Budget", style="yellow", justify="right")
+    table.add_column("Expected output", style="white")
+    for phase in plan.phases:
+        table.add_row(phase.name, str(phase.max_actions), phase.expected_output)
+    console.print(table)
+    console.print(
+        Panel(
+            plan.generated_stop_prompt,
+            title="Pasteable phase-gated prompt",
+            border_style="magenta",
+            box=box.ROUNDED,
+        )
+    )
+
+
+def _print_config(config: ForesightConfig) -> None:
+    """Render effective configuration with the file that supplied it."""
+
+    table = Table(title="Active Foresight configuration", box=box.ROUNDED, border_style=ACCENT)
+    table.add_column("Setting", style=f"bold {ACCENT}")
+    table.add_column("Value", style="white")
+    for name, value in (
+        ("default_tier_bias", config.default_tier_bias),
+        ("dashboard_url", config.dashboard_url),
+        ("eventbus_host", config.eventbus_host),
+        ("eventbus_port", str(config.eventbus_port)),
+        ("isolated_ceiling_usd", f"${config.isolated_ceiling_usd:.2f}"),
+        ("moderate_ceiling_usd", f"${config.moderate_ceiling_usd:.2f}"),
+        ("wide_ceiling_usd", f"${config.wide_ceiling_usd:.2f}"),
+        ("source", str(config.source) if config.source else "built-in defaults"),
+    ):
+        table.add_row(name, value)
+    console.print(table)
+
+
+@click.group(context_settings={"help_option_names": []}, invoke_without_command=True)
+@click.option("-h", "--help", "show_help", is_flag=True, is_eager=True, expose_value=False, callback=_show_help)
+@click.version_option(VERSION, "--version", message=f"Foresight v{VERSION}")
+@click.pass_context
+def main(context: click.Context) -> None:
+    """Predict, monitor, and audit AI coding-agent sessions."""
+
+    try:
+        context.ensure_object(dict)
+        context.obj["config"] = load_config()
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+    if context.invoked_subcommand is None:
+        _print_banner()
+        _print_command_table()
+
+
+@main.command(help="Infer policy and tier prediction from an interactive task scope.")
+@click.pass_context
+def init(context: click.Context) -> None:
+    """Create and optionally save a policy and prediction for a task."""
+
+    _print_banner()
+    _print_header("INIT", "describe the task boundary")
+    config: ForesightConfig = context.find_root().obj["config"]
+    scope = click.prompt("Task scope")
+    tracker = create_cost_tracker()
+    policy = scope_to_policy(scope, tracker)
+    prediction = predict_complexity(scope, tracker, tier_bias=config.default_tier_bias)
+
+    table = Table(title="Foresight session plan", box=box.ROUNDED, border_style=ACCENT)
+    table.add_column("Policy scope", style="white")
+    table.add_column("Predicted tier", style=f"bold {ACCENT}")
+    table.add_column("Effort", style="yellow")
+    table.add_column("Blast radius", style="magenta")
+    table.add_row(
+        ", ".join(policy.allowed_paths) or "(none)",
+        prediction["predicted_tier"],
+        prediction["predicted_effort"],
+        prediction["estimated_blast_radius"],
+    )
+    console.print(table)
+    if advisory := prediction.get("effort_advisory"):
+        console.print(f"[dim]Effort guidance: {advisory}[/dim]")
+
+    workflow_plan = None
+    if click.confirm("Generate a phased workflow plan for this task?", default=False):
+        workflow_plan = generate_workflow_plan(scope, tracker)
+        _print_workflow_plan(workflow_plan)
+
+    if not click.confirm("Save this session plan?", default=True):
+        console.print("[dim]Session plan not saved.[/dim]")
+        return
+
+    STATE.mkdir(exist_ok=True)
+    (STATE / "policy.json").write_text(json.dumps(asdict(policy), indent=2), encoding="utf-8")
+    (STATE / "prediction.json").write_text(json.dumps(prediction, indent=2), encoding="utf-8")
+    (STATE / "scope.txt").write_text(scope, encoding="utf-8")
+    workflow_path = STATE / "workflow_plan.json"
+    if workflow_plan is not None:
+        workflow_path.write_text(json.dumps(asdict(workflow_plan), indent=2), encoding="utf-8")
+    elif workflow_path.exists():
+        workflow_path.unlink()
+    console.print(f"[bold green]OK[/bold green] Saved session plan in [cyan]{STATE}[/cyan]")
+
+
+@main.command(context_settings={"ignore_unknown_options": True}, help="Run a command under Sentry and Foresight monitoring.")
+@click.argument("command", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def run(context: click.Context, command: tuple[str, ...]) -> None:
+    """Run one command through the existing monitoring pipeline."""
+
+    _print_banner()
+    if not command:
+        raise click.UsageError("Pass a command after --, for example: foresight run -- python task.py")
+
+    _print_header("RUN", "starting monitored command")
+    config: ForesightConfig = context.find_root().obj["config"]
+    policy, predicted, workflow_plan = _load()
+    scope_path = STATE / "scope.txt"
+    scope = scope_path.read_text(encoding="utf-8") if scope_path.exists() else "Saved Foresight session"
+    tracker = create_cost_tracker()
+    thread = threading.Thread(target=_server, args=(config,), daemon=True)
+    thread.start()
+
+    session_id = f"foresight-{uuid.uuid4().hex[:8]}"
+    proxy = create_sentry_proxy(session_id, policy, lambda action, active_policy: evaluate_action(action, active_policy, tracker))
+    monitor = SessionMonitor(
+        scope,
+        predicted,
+        proxy,
+        broadcast_signal,
+        tracker,
+        workflow_plan=workflow_plan,
+        budget_overrides=config.budget_overrides,
+    )
+    killed = False
+
+    console.print(
+        Panel.fit(
+            f"[bold {ACCENT}]MONITORING[/bold {ACCENT}]\n[white]{' '.join(command)}[/white]",
+            title="Foresight run",
+            border_style=ACCENT,
+            box=box.ROUNDED,
+        )
+    )
+    if advisory := predicted.get("effort_advisory"):
+        console.print(f"[dim]Effort guidance: {advisory}[/dim]")
+    if workflow_plan is not None:
+        _print_workflow_plan(workflow_plan)
+    console.print(f"[dim]Dashboard: {config.dashboard_url}[/dim]")
+    try:
+        with proxy:
+            subprocess.run(list(command), check=False)
+    except SentryBlockedException as error:
+        killed = True
+        console.print(f"[bold red]BLOCKED[/bold red] {error}")
+
+    report = monitor.get_session_report()
+    STATE.mkdir(exist_ok=True)
+    (STATE / "last_report.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
+    color = "red" if killed else ("yellow" if report["flags_raised"] else "green")
+    console.print(
+        Panel(
+            json.dumps(report, indent=2),
+            title=f"[{color}]Foresight session report[/{color}]",
+            border_style=color,
+            box=box.ROUNDED,
+        )
+    )
+    if killed:
+        raise click.exceptions.Exit(1)
+
+
+@main.command(help="Show the last saved Foresight session report.")
+def status() -> None:
+    """Print the final report from the most recent monitored run."""
+
+    _print_header("STATUS", "last saved session report")
+    path = STATE / "last_report.json"
+    if not path.exists():
+        raise click.ClickException("No completed session report yet.")
+    console.print(
+        Panel(
+            path.read_text(encoding="utf-8"),
+            title="Foresight session report",
+            border_style=ACCENT,
+            box=box.ROUNDED,
+        )
+    )
+
+
+@main.command(help="Export the in-memory audit log.")
+@click.option("--session", default=None, help="Session label displayed with the export.")
+def export(session: str | None) -> None:
+    """Write the in-memory event bus audit log to JSON."""
+
+    _print_header("EXPORT", "writing audit log")
+    path = export_audit_log()
+    suffix = f" for {session}" if session else ""
+    console.print(f"[bold green]OK[/bold green] Audit exported: [cyan]{path}[/cyan]{suffix}")
+
+
+@main.group(help="Create or inspect user-editable Foresight defaults.")
+def config() -> None:
+    """Manage the optional project-local ``foresight.toml`` file."""
+
+
+@config.command("init", help="Write a commented default foresight.toml in the current directory.")
+def config_init() -> None:
+    """Create the project-local configuration template without overwriting it."""
+
+    _print_header("CONFIG", "creating project-local defaults")
+    path = Path.cwd() / "foresight.toml"
+    try:
+        write_default_config(path)
+    except FileExistsError as error:
+        raise click.ClickException(str(error)) from error
+    console.print(f"[bold green]OK[/bold green] Created [cyan]{path}[/cyan]")
+
+
+@config.command("show", help="Print the merged effective config and its source.")
+@click.pass_context
+def config_show(context: click.Context) -> None:
+    """Display active defaults after optional TOML values override built-ins."""
+
+    _print_header("CONFIG", "active merged defaults")
+    _print_config(context.find_root().obj["config"])
+
+
+if __name__ == "__main__":
+    main()

foresight/config.py

@@ -0,0 +1,139 @@
+"""User-editable Foresight defaults loaded from TOML without requiring setup."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+VALID_TIER_BIASES = {"balanced", "cost_optimized", "quality_optimized"}
+DEFAULT_CONFIG_TEXT = """# Foresight user defaults. Values in this file override built-in defaults.
+
+[defaults]
+# balanced, cost_optimized, or quality_optimized. This nudges tier recommendations.
+default_tier_bias = "balanced"
+# Where the local dashboard is expected to be available.
+dashboard_url = "http://localhost:3000/dashboard"
+# Local WebSocket event bus address used by `foresight run`.
+eventbus_host = "localhost"
+eventbus_port = 8765
+
+[budgets]
+# Per-session warning ceilings in USD, selected from predicted blast radius.
+isolated_ceiling_usd = 0.10
+moderate_ceiling_usd = 0.50
+wide_ceiling_usd = 2.00
+"""
+
+
+@dataclass(frozen=True)
+class ForesightConfig:
+    """Effective configuration after built-in defaults and one TOML file are merged."""
+
+    default_tier_bias: str = "balanced"
+    dashboard_url: str = "http://localhost:3000/dashboard"
+    eventbus_host: str = "localhost"
+    eventbus_port: int = 8765
+    isolated_ceiling_usd: float = 0.10
+    moderate_ceiling_usd: float = 0.50
+    wide_ceiling_usd: float = 2.00
+    source: Path | None = None
+
+    @property
+    def budget_overrides(self) -> dict[str, float]:
+        """Return monitor ceilings keyed by predicted blast radius."""
+
+        return {
+            "isolated": self.isolated_ceiling_usd,
+            "moderate": self.moderate_ceiling_usd,
+            "wide": self.wide_ceiling_usd,
+        }
+
+
+def user_config_path() -> Path:
+    """Return the platform-appropriate per-user configuration path."""
+
+    if os.name == "nt":
+        root = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+        return root / "foresight" / "config.toml"
+    return Path.home() / ".config" / "foresight" / "config.toml"
+
+
+def find_config_path(cwd: Path | None = None) -> Path | None:
+    """Prefer ``foresight.toml`` in the working directory, then user config."""
+
+    local = (cwd or Path.cwd()) / "foresight.toml"
+    if local.is_file():
+        return local
+    user = user_config_path()
+    return user if user.is_file() else None
+
+
+def load_config(cwd: Path | None = None) -> ForesightConfig:
+    """Load optional TOML settings, keeping zero-config defaults when absent."""
+
+    path = find_config_path(cwd)
+    if path is None:
+        return ForesightConfig()
+    try:
+        # ``utf-8-sig`` accepts files written by Windows editors that add a BOM.
+        raw = tomllib.loads(path.read_text(encoding="utf-8-sig"))
+    except tomllib.TOMLDecodeError as error:
+        raise ValueError(f"Invalid Foresight config at {path}: {error}") from error
+
+    defaults = _section(raw, "defaults")
+    budgets = _section(raw, "budgets")
+    tier_bias = str(defaults.get("default_tier_bias", "balanced"))
+    if tier_bias not in VALID_TIER_BIASES:
+        raise ValueError(f"default_tier_bias must be one of: {', '.join(sorted(VALID_TIER_BIASES))}")
+
+    config = ForesightConfig(
+        default_tier_bias=tier_bias,
+        dashboard_url=str(defaults.get("dashboard_url", "http://localhost:3000/dashboard")),
+        eventbus_host=str(defaults.get("eventbus_host", "localhost")),
+        eventbus_port=_positive_int(defaults.get("eventbus_port", 8765), "eventbus_port"),
+        isolated_ceiling_usd=_positive_float(budgets.get("isolated_ceiling_usd", 0.10), "isolated_ceiling_usd"),
+        moderate_ceiling_usd=_positive_float(budgets.get("moderate_ceiling_usd", 0.50), "moderate_ceiling_usd"),
+        wide_ceiling_usd=_positive_float(budgets.get("wide_ceiling_usd", 2.00), "wide_ceiling_usd"),
+        source=path,
+    )
+    return config
+
+
+def write_default_config(path: Path) -> Path:
+    """Create a commented project-local config file without overwriting one."""
+
+    if path.exists():
+        raise FileExistsError(f"Config already exists: {path}")
+    path.write_text(DEFAULT_CONFIG_TEXT, encoding="utf-8")
+    return path
+
+
+def _section(raw: dict[str, Any], name: str) -> dict[str, Any]:
+    value = raw.get(name, {})
+    if not isinstance(value, dict):
+        raise ValueError(f"[{name}] must be a TOML table")
+    return value
+
+
+def _positive_int(value: Any, name: str) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"{name} must be a positive integer") from error
+    if parsed <= 0:
+        raise ValueError(f"{name} must be a positive integer")
+    return parsed
+
+
+def _positive_float(value: Any, name: str) -> float:
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"{name} must be a positive number") from error
+    if parsed <= 0:
+        raise ValueError(f"{name} must be a positive number")
+    return parsed