agentsecure 0.1.7__tar.gz → 0.1.9__tar.gz

{agentsecure-0.1.7/agentsecure.egg-info → agentsecure-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentsecure
-Version: 0.1.7
+Version: 0.1.9
 Summary: Local-first security runtime for AI coding agents
 Home-page: https://github.com/ShellFrameAI/agentsecure-community
 Author: ShellFrame AI
@@ -76,6 +76,23 @@ python3 -m agentsecure run claude
 
 Keep real secrets in one local AgentSecure vault:
 
+```bash
+agentsecure secrets import .env
+agentsecure run -- claude
+```
+
+`secrets import` is the easiest migration path. It scans the dotenv file, stores discovered real secret values in the local vault, assigns those aliases to the current project, writes a private backup under `~/.agentsecure/backups/`, and replaces the values in `.env` with non-secret `AGENTSECURE_ALIAS_...` placeholders.
+
+Use `--dry-run` to preview the import, or `--keep-file` if you want to store aliases without rewriting `.env`.
+
+To undo the rewrite and bring the original `.env` back from the latest private backup:
+
+```bash
+agentsecure secrets restore .env
+```
+
+For manual control, add one alias at a time:
+
 ```bash
 printf '%s' "$DATABASE_URL" | agentsecure secrets add dev_db \
   --env-name DATABASE_URL \
@@ -97,6 +114,23 @@ What this does:
 
 Do not put real secrets in project `.env` files. Use `.env` for non-secret config or fake placeholders that are safe for an agent to read.
 
+## Agent Run Guidance
+
+Every `agentsecure run` creates a small per-run guide under `.agentsecure/runs/` and prints its relative path:
+
+```text
+AgentSecure agent guide: .agentsecure/runs/run_.../AGENTSECURE_AGENT_GUIDE.md
+```
+
+The launched agent receives the absolute guide path in both `AGENTSECURE_AGENT_GUIDE` and `AGENTSECURE_SKILL_FILE`. The file contains only operational guidance and safe metadata, such as managed secret environment variable names, providers, and approved hosts from runtime alias bindings when available. It does not include raw secrets or virtual token values.
+
+Agents should use the injected environment variables and virtual tokens. They should not read `.env` to recover secrets or ask a human to paste secrets. If an expected secret env var is missing, ask the user to run:
+
+```bash
+agentsecure secrets import .env
+agentsecure secrets use <alias>
+```
+
 ## What The Demo Shows
 
 The built-in demo creates a temporary local project with fake secrets, applies a small sample policy, simulates a command reading `.env`, and prints what the agent would see:

{agentsecure-0.1.7 → agentsecure-0.1.9}/README.md

@@ -50,6 +50,23 @@ python3 -m agentsecure run claude
 
 Keep real secrets in one local AgentSecure vault:
 
+```bash
+agentsecure secrets import .env
+agentsecure run -- claude
+```
+
+`secrets import` is the easiest migration path. It scans the dotenv file, stores discovered real secret values in the local vault, assigns those aliases to the current project, writes a private backup under `~/.agentsecure/backups/`, and replaces the values in `.env` with non-secret `AGENTSECURE_ALIAS_...` placeholders.
+
+Use `--dry-run` to preview the import, or `--keep-file` if you want to store aliases without rewriting `.env`.
+
+To undo the rewrite and bring the original `.env` back from the latest private backup:
+
+```bash
+agentsecure secrets restore .env
+```
+
+For manual control, add one alias at a time:
+
 ```bash
 printf '%s' "$DATABASE_URL" | agentsecure secrets add dev_db \
   --env-name DATABASE_URL \
@@ -71,6 +88,23 @@ What this does:
 
 Do not put real secrets in project `.env` files. Use `.env` for non-secret config or fake placeholders that are safe for an agent to read.
 
+## Agent Run Guidance
+
+Every `agentsecure run` creates a small per-run guide under `.agentsecure/runs/` and prints its relative path:
+
+```text
+AgentSecure agent guide: .agentsecure/runs/run_.../AGENTSECURE_AGENT_GUIDE.md
+```
+
+The launched agent receives the absolute guide path in both `AGENTSECURE_AGENT_GUIDE` and `AGENTSECURE_SKILL_FILE`. The file contains only operational guidance and safe metadata, such as managed secret environment variable names, providers, and approved hosts from runtime alias bindings when available. It does not include raw secrets or virtual token values.
+
+Agents should use the injected environment variables and virtual tokens. They should not read `.env` to recover secrets or ask a human to paste secrets. If an expected secret env var is missing, ask the user to run:
+
+```bash
+agentsecure secrets import .env
+agentsecure secrets use <alias>
+```
+
 ## What The Demo Shows
 
 The built-in demo creates a temporary local project with fake secrets, applies a small sample policy, simulates a command reading `.env`, and prints what the agent would see:

{agentsecure-0.1.7 → agentsecure-0.1.9}/agentsecure/__init__.py

@@ -1,3 +1,3 @@
 """AgentSecure local-first security runtime."""
 
-__version__ = "0.1.7"
+__version__ = "0.1.9"

{agentsecure-0.1.7 → agentsecure-0.1.9}/agentsecure/cli/main.py

@@ -5,6 +5,7 @@ import ipaddress
 import json
 import os
 import queue
+import re
 import shutil
 import socket
 import subprocess
@@ -14,6 +15,7 @@ import threading
 import time
 import uuid
 from typing import Any, Dict, List, Optional
+from urllib.parse import urlsplit
 from urllib.request import Request, urlopen
 
 from agentsecure import __version__
@@ -54,6 +56,12 @@ from agentsecure.cli.settings import (
 )
 from agentsecure.client.wrappers import AgentWrapperInstaller, SUPPORTED_AGENTS
 from agentsecure.core.agentsecure_md import AGENTSECURE_MD, agentsecure_md_status
+from agentsecure.core.agent_guidance import (
+    ENV_AGENT_GUIDE,
+    ENV_SKILL_FILE,
+    relative_agent_guidance_path,
+    write_agent_guidance,
+)
 from agentsecure.core.command_metadata import safe_command_metadata
 from agentsecure.core.config import ConfigError, JsonConfigLoader, JsonConfigWriter
 from agentsecure.core.config_profiles import (
@@ -256,6 +264,17 @@ def build_parser() -> argparse.ArgumentParser:
     use_secret_parser = secrets_subparsers.add_parser("use", help="Assign aliases to this project")
     use_secret_parser.add_argument("alias_ids", nargs="+")
     use_secret_parser.add_argument("--project", default="", help="Project name for audit metadata")
+    import_secret_parser = secrets_subparsers.add_parser("import", help="Move secrets from a dotenv file into the local vault")
+    import_secret_parser.add_argument("path", nargs="?", default=".env", help="Dotenv file to import, default .env")
+    import_secret_parser.add_argument("--project", default="", help="Project name for audit metadata")
+    import_secret_parser.add_argument("--approved-host", action="append", default=[], help="Additional host allowed to receive imported secrets")
+    import_secret_parser.add_argument("--keep-file", action="store_true", help="Do not rewrite the dotenv file after importing")
+    import_secret_parser.add_argument("--no-backup", action="store_true", help="Do not store a local backup before rewriting")
+    import_secret_parser.add_argument("--dry-run", action="store_true", help="Show what would be imported without writing changes")
+    restore_secret_parser = secrets_subparsers.add_parser("restore", help="Restore a dotenv file from the latest AgentSecure backup")
+    restore_secret_parser.add_argument("path", nargs="?", default=".env", help="Dotenv file to restore, default .env")
+    restore_secret_parser.add_argument("--backup", default="", help="Specific backup file to restore instead of the latest backup")
+    restore_secret_parser.add_argument("--dry-run", action="store_true", help="Show which backup would be restored")
 
     subparsers.add_parser("discover", help="Discover likely local secrets")
     subparsers.add_parser("suggest", help="Suggest env and network policy for discovered secrets")
@@ -367,7 +386,8 @@ def run_agent(args: argparse.Namespace) -> int:
     runtime_bindings = alias_runtime_bindings
     container = Container.from_config_path(args.config, runtime_bindings=runtime_bindings, run_id=run_id)
     replacements.extend(_configured_secret_replacements(container, replacements))
-    run_cwd = os.getcwd()
+    source_root = os.getcwd()
+    run_cwd = source_root
     workspace_session = None
     materializer = WorkspaceMaterializer(_workspace_base_for_runtime(run_cwd, args.runtime))
     should_create_workspace = bool(replacements or container.config.files.protect_write)
@@ -453,6 +473,24 @@ def run_agent(args: argparse.Namespace) -> int:
         env[ENV_RUNTIME_BINDINGS] = serialize_runtime_bindings(runtime_bindings)
         env["AGENTSECURE_RUN_ID"] = run_id
         env["AGENTSECURE_PROJECT_ID"] = project_id
+    try:
+        agent_guide_path = write_agent_guidance(source_root, run_id, runtime_bindings)
+    except OSError as exc:
+        sys.stderr.write("agentsecure: failed to create agent guidance file: %s\n" % exc)
+        return 1
+    env[ENV_SKILL_FILE] = agent_guide_path
+    env[ENV_AGENT_GUIDE] = agent_guide_path
+    relative_guide_path = relative_agent_guidance_path(source_root, agent_guide_path)
+    container.audit_logger.record(
+        "agent_guidance_created",
+        {
+            "run_id": run_id,
+            "project_id": project_id,
+            "path": relative_guide_path,
+            "aliases": [binding.alias_id or binding.env_name for binding in runtime_bindings],
+        },
+    )
+    print("AgentSecure agent guide: %s" % relative_guide_path, flush=True)
     if args.runtime == "command-guard":
         CommandGuardWrapperInstaller(args.config).install(env)
     session_id = daemon_session.get("session_id", "") if daemon_session else ""
@@ -1149,6 +1187,10 @@ def handle_secret_aliases(args: argparse.Namespace) -> int:
         return list_secret_aliases(args)
     if args.secrets_command == "use":
         return use_secret_aliases(args)
+    if args.secrets_command == "import":
+        return import_secret_aliases(args)
+    if args.secrets_command == "restore":
+        return restore_dotenv_from_backup(args)
     sys.stderr.write("agentsecure: missing secrets subcommand\n")
     return 2
 
@@ -1242,6 +1284,263 @@ def use_secret_aliases(args: argparse.Namespace) -> int:
     return 0
 
 
+def import_secret_aliases(args: argparse.Namespace) -> int:
+    dotenv_path = os.path.abspath(args.path)
+    if not os.path.exists(dotenv_path):
+        sys.stderr.write("agentsecure: dotenv file not found: %s\n" % args.path)
+        return 2
+    source_dir = os.path.dirname(dotenv_path) or "."
+    source_name = os.path.basename(dotenv_path)
+    discoveries = DotenvSecretScanner(source_dir, [source_name]).scan()
+    discoveries = [secret for secret in discoveries if secret.source == source_name]
+    if not discoveries:
+        print(
+            json.dumps(
+                {
+                    "imported": [],
+                    "dotenv": args.path,
+                    "message": "No secrets found",
+                },
+                indent=2,
+                sort_keys=True,
+            )
+        )
+        return 0
+
+    imports = []
+    for secret in discoveries:
+        alias_id = _alias_id_for_env_name(secret.name)
+        approved_hosts = _approved_hosts_for_import(secret, args.approved_host)
+        imports.append(
+            {
+                "alias_id": alias_id,
+                "env_name": secret.name,
+                "provider": secret.provider_hint,
+                "approved_hosts": approved_hosts,
+                "placeholder": _alias_placeholder(alias_id),
+            }
+        )
+
+    if args.dry_run:
+        print(
+            json.dumps(
+                {
+                    "dotenv": args.path,
+                    "imported": imports,
+                    "would_rewrite_dotenv": not args.keep_file,
+                    "dry_run": True,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+        )
+        return 0
+
+    service = _secret_alias_service(args.config)
+    try:
+        for secret, item in zip(discoveries, imports):
+            service.add_alias(
+                alias_id=item["alias_id"],
+                real_secret=secret.value,
+                env_name=secret.name,
+                provider=secret.provider_hint,
+                approved_hosts=item["approved_hosts"],
+                name=secret.name,
+            )
+        assigned = service.assign_to_project(
+            args.config,
+            [item["alias_id"] for item in imports],
+            project=args.project or os.path.basename(os.getcwd()) or "default",
+        )
+    except SecretAliasError as exc:
+        sys.stderr.write("agentsecure: %s\n" % exc)
+        return 2
+
+    backup_path = ""
+    if not args.keep_file:
+        if not args.no_backup:
+            try:
+                backup_path = _backup_dotenv_to_vault(dotenv_path, args.config)
+            except OSError as exc:
+                sys.stderr.write("agentsecure: failed to back up dotenv file: %s\n" % exc)
+                return 1
+        try:
+            _rewrite_dotenv_with_alias_placeholders(dotenv_path, {item["env_name"]: item["placeholder"] for item in imports})
+        except OSError as exc:
+            sys.stderr.write("agentsecure: failed to rewrite dotenv file: %s\n" % exc)
+            return 1
+
+    print(
+        json.dumps(
+            {
+                "dotenv": args.path,
+                "backup": backup_path,
+                "rewritten": not args.keep_file,
+                "imported": [
+                    {
+                        "alias_id": item.alias_id,
+                        "env_name": item.env_name,
+                        "provider": item.provider,
+                        "approved_hosts": item.approved_hosts,
+                    }
+                    for item in assigned
+                ],
+                "real_secrets_stored": "local_vault",
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+def restore_dotenv_from_backup(args: argparse.Namespace) -> int:
+    dotenv_path = os.path.abspath(args.path)
+    backup_path = os.path.abspath(args.backup) if args.backup else _latest_dotenv_backup(dotenv_path, args.config)
+    if not backup_path:
+        sys.stderr.write("agentsecure: no backup found for %s\n" % args.path)
+        return 2
+    if not os.path.exists(backup_path):
+        sys.stderr.write("agentsecure: backup file not found: %s\n" % backup_path)
+        return 2
+    if args.dry_run:
+        print(
+            json.dumps(
+                {
+                    "dotenv": args.path,
+                    "backup": backup_path,
+                    "would_restore": True,
+                    "dry_run": True,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+        )
+        return 0
+    try:
+        shutil.copy2(backup_path, dotenv_path)
+    except OSError as exc:
+        sys.stderr.write("agentsecure: failed to restore dotenv file: %s\n" % exc)
+        return 1
+    print(
+        json.dumps(
+            {
+                "dotenv": args.path,
+                "backup": backup_path,
+                "restored": True,
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+def _alias_id_for_env_name(env_name: str) -> str:
+    normalized = re.sub(r"[^a-z0-9._-]+", "_", str(env_name).strip().lower())
+    normalized = normalized.strip("._-")
+    return normalized or "secret"
+
+
+def _alias_placeholder(alias_id: str) -> str:
+    return "AGENTSECURE_ALIAS_%s" % re.sub(r"[^A-Z0-9]+", "_", alias_id.upper()).strip("_")
+
+
+def _approved_hosts_for_import(secret: DiscoveredSecret, extra_hosts: List[str]) -> List[str]:
+    hosts = []
+    inferred = _host_from_secret_value(secret.value)
+    if inferred:
+        hosts.append(inferred)
+    provider_hosts = {
+        "openai": "api.openai.com",
+        "anthropic": "api.anthropic.com",
+        "github": "api.github.com",
+        "stripe": "api.stripe.com",
+    }
+    provider_host = provider_hosts.get(secret.provider_hint)
+    if provider_host:
+        hosts.append(provider_host)
+    hosts.extend(extra_hosts or [])
+    result = []
+    seen = set()
+    for host in hosts:
+        normalized = str(host).strip().lower().rstrip(".")
+        if normalized and normalized not in seen:
+            result.append(normalized)
+            seen.add(normalized)
+    return result
+
+
+def _host_from_secret_value(value: str) -> str:
+    try:
+        parsed = urlsplit(str(value).strip())
+    except ValueError:
+        return ""
+    return (parsed.hostname or "").strip().lower().rstrip(".")
+
+
+def _backup_dotenv_to_vault(dotenv_path: str, config_path: str) -> str:
+    backup_dir = os.path.join(agentsecure_home(), "backups", project_id_for_path(config_path))
+    os.makedirs(backup_dir, exist_ok=True)
+    backup_path = os.path.join(
+        backup_dir,
+        "%s.%s.bak" % (os.path.basename(dotenv_path), time.strftime("%Y%m%d%H%M%S")),
+    )
+    shutil.copy2(dotenv_path, backup_path)
+    os.chmod(backup_path, 0o600)
+    return backup_path
+
+
+def _latest_dotenv_backup(dotenv_path: str, config_path: str) -> str:
+    backup_dir = os.path.join(agentsecure_home(), "backups", project_id_for_path(config_path))
+    if not os.path.isdir(backup_dir):
+        return ""
+    prefix = os.path.basename(dotenv_path) + "."
+    candidates = []
+    for filename in os.listdir(backup_dir):
+        if filename.startswith(prefix) and filename.endswith(".bak"):
+            path = os.path.join(backup_dir, filename)
+            if os.path.isfile(path):
+                candidates.append(path)
+    if not candidates:
+        return ""
+    candidates.sort(key=lambda path: (os.path.getmtime(path), path), reverse=True)
+    return candidates[0]
+
+
+def _rewrite_dotenv_with_alias_placeholders(dotenv_path: str, placeholders: Dict[str, str]) -> None:
+    with open(dotenv_path, "r") as handle:
+        lines = handle.readlines()
+    rewritten = []
+    for line in lines:
+        parsed_name = _dotenv_line_name(line)
+        if parsed_name and parsed_name in placeholders:
+            prefix = line.split("=", 1)[0].rstrip()
+            newline = "\n" if line.endswith("\n") else ""
+            rewritten.append("%s=%s%s" % (prefix, placeholders[parsed_name], newline))
+        else:
+            rewritten.append(line)
+    fd, temp_path = tempfile.mkstemp(prefix=".agentsecure-dotenv-", dir=os.path.dirname(dotenv_path) or ".")
+    try:
+        with os.fdopen(fd, "w") as handle:
+            handle.writelines(rewritten)
+        shutil.copymode(dotenv_path, temp_path)
+        os.replace(temp_path, dotenv_path)
+    finally:
+        if os.path.exists(temp_path):
+            os.unlink(temp_path)
+
+
+def _dotenv_line_name(line: str) -> str:
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#") or "=" not in stripped:
+        return ""
+    name = stripped.split("=", 1)[0].strip()
+    if name.startswith("export "):
+        name = name[len("export ") :].strip()
+    return name
+
+
 def _secret_alias_service(config_path: str) -> SecretAliasService:
     home = agentsecure_home()
     return SecretAliasService(

agentsecure-0.1.9/agentsecure/core/agent_guidance.py

@@ -0,0 +1,69 @@
+import os
+from typing import Iterable, List
+
+from agentsecure.core.models import SecretBinding
+
+
+AGENT_GUIDE_FILENAME = "AGENTSECURE_AGENT_GUIDE.md"
+ENV_AGENT_GUIDE = "AGENTSECURE_AGENT_GUIDE"
+ENV_SKILL_FILE = "AGENTSECURE_SKILL_FILE"
+
+
+def write_agent_guidance(source_root: str, run_id: str, bindings: Iterable[SecretBinding]) -> str:
+    guide_dir = os.path.abspath(os.path.join(source_root, ".agentsecure", "runs", run_id))
+    os.makedirs(guide_dir, exist_ok=True)
+    os.chmod(guide_dir, 0o700)
+    guide_path = os.path.join(guide_dir, AGENT_GUIDE_FILENAME)
+    fd = os.open(guide_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as handle:
+        handle.write(render_agent_guidance(bindings))
+    os.chmod(guide_path, 0o600)
+    return guide_path
+
+
+def render_agent_guidance(bindings: Iterable[SecretBinding]) -> str:
+    binding_list = sorted(list(bindings), key=lambda item: (item.env_name, item.provider, item.alias_id))
+    lines: List[str] = [
+        "# AgentSecure Run Guidance",
+        "",
+        "- Use the environment variables AgentSecure injected for this run.",
+        "- Treat values beginning with `virt_` as virtual tokens, not raw secrets.",
+        "- Do not read `.env` files to recover secrets.",
+        "- Do not ask a human to paste secrets into chat, terminal, logs, or files.",
+        "- If a required secret environment variable is missing, ask the user to run `agentsecure secrets import .env` or `agentsecure secrets use <alias>` before retrying.",
+        "",
+    ]
+    if binding_list:
+        lines.extend(["## Managed Secret Environment", ""])
+        for binding in binding_list:
+            details = [
+                "env=%s" % _safe_text(binding.env_name),
+                "provider=%s" % _safe_text(binding.provider or "custom"),
+            ]
+            if binding.approved_hosts:
+                details.append("approved_hosts=%s" % ", ".join(_safe_text(host) for host in binding.approved_hosts))
+            else:
+                details.append("approved_hosts=not specified")
+            lines.append("- " + "; ".join(details))
+        lines.append("")
+    else:
+        lines.extend(
+            [
+                "## Managed Secret Environment",
+                "",
+                "- No runtime alias bindings were provided for this run.",
+                "",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def relative_agent_guidance_path(source_root: str, guide_path: str) -> str:
+    try:
+        return os.path.relpath(guide_path, os.path.abspath(source_root))
+    except ValueError:
+        return guide_path
+
+
+def _safe_text(value: str) -> str:
+    return str(value).replace("\n", " ").replace("\r", " ").strip()

{agentsecure-0.1.7 → agentsecure-0.1.9/agentsecure.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentsecure
-Version: 0.1.7
+Version: 0.1.9
 Summary: Local-first security runtime for AI coding agents
 Home-page: https://github.com/ShellFrameAI/agentsecure-community
 Author: ShellFrame AI
@@ -76,6 +76,23 @@ python3 -m agentsecure run claude
 
 Keep real secrets in one local AgentSecure vault:
 
+```bash
+agentsecure secrets import .env
+agentsecure run -- claude
+```
+
+`secrets import` is the easiest migration path. It scans the dotenv file, stores discovered real secret values in the local vault, assigns those aliases to the current project, writes a private backup under `~/.agentsecure/backups/`, and replaces the values in `.env` with non-secret `AGENTSECURE_ALIAS_...` placeholders.
+
+Use `--dry-run` to preview the import, or `--keep-file` if you want to store aliases without rewriting `.env`.
+
+To undo the rewrite and bring the original `.env` back from the latest private backup:
+
+```bash
+agentsecure secrets restore .env
+```
+
+For manual control, add one alias at a time:
+
 ```bash
 printf '%s' "$DATABASE_URL" | agentsecure secrets add dev_db \
   --env-name DATABASE_URL \
@@ -97,6 +114,23 @@ What this does:
 
 Do not put real secrets in project `.env` files. Use `.env` for non-secret config or fake placeholders that are safe for an agent to read.
 
+## Agent Run Guidance
+
+Every `agentsecure run` creates a small per-run guide under `.agentsecure/runs/` and prints its relative path:
+
+```text
+AgentSecure agent guide: .agentsecure/runs/run_.../AGENTSECURE_AGENT_GUIDE.md
+```
+
+The launched agent receives the absolute guide path in both `AGENTSECURE_AGENT_GUIDE` and `AGENTSECURE_SKILL_FILE`. The file contains only operational guidance and safe metadata, such as managed secret environment variable names, providers, and approved hosts from runtime alias bindings when available. It does not include raw secrets or virtual token values.
+
+Agents should use the injected environment variables and virtual tokens. They should not read `.env` to recover secrets or ask a human to paste secrets. If an expected secret env var is missing, ask the user to run:
+
+```bash
+agentsecure secrets import .env
+agentsecure secrets use <alias>
+```
+
 ## What The Demo Shows
 
 The built-in demo creates a temporary local project with fake secrets, applies a small sample policy, simulates a command reading `.env`, and prints what the agent would see:

{agentsecure-0.1.7 → agentsecure-0.1.9}/agentsecure.egg-info/SOURCES.txt

@@ -30,6 +30,7 @@ agentsecure/client/wrappers.py
 agentsecure/config/__init__.py
 agentsecure/config/default_agentsecure.json
 agentsecure/core/__init__.py
+agentsecure/core/agent_guidance.py
 agentsecure/core/agentsecure_md.py
 agentsecure/core/capabilities.py
 agentsecure/core/command_metadata.py
@@ -88,6 +89,7 @@ agentsecure/workspace/diff.py
 agentsecure/workspace/materializer.py
 agentsecure/workspace/rewriter.py
 agentsecure/workspace/strategies.py
+tests/test_agent_guidance.py
 tests/test_agentsecure_md.py
 tests/test_audit.py
 tests/test_cli.py

{agentsecure-0.1.7 → agentsecure-0.1.9}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = agentsecure
-version = 0.1.7
+version = 0.1.9
 description = Local-first security runtime for AI coding agents
 long_description = file: README.md
 long_description_content_type = text/markdown

agentsecure-0.1.9/tests/test_agent_guidance.py

@@ -0,0 +1,54 @@
+import os
+import tempfile
+import unittest
+
+from agentsecure.core.agent_guidance import (
+    AGENT_GUIDE_FILENAME,
+    render_agent_guidance,
+    relative_agent_guidance_path,
+    write_agent_guidance,
+)
+from agentsecure.core.models import SecretBinding
+
+
+class AgentGuidanceTest(unittest.TestCase):
+    def test_renders_managed_bindings_without_virtual_or_real_secret_values(self):
+        text = render_agent_guidance(
+            [
+                SecretBinding(
+                    env_name="OPENAI_API_KEY",
+                    virtual_token="virt_openai_should_not_be_written",
+                    real_secret_ref="vault://secret-ref-should-not-be-written",
+                    provider="openai",
+                    alias_id="openai_dev",
+                    approved_hosts=["api.openai.com"],
+                )
+            ]
+        )
+
+        self.assertIn("OPENAI_API_KEY", text)
+        self.assertIn("provider=openai", text)
+        self.assertIn("approved_hosts=api.openai.com", text)
+        self.assertIn("Do not read `.env` files", text)
+        self.assertIn("agentsecure secrets import .env", text)
+        self.assertIn("agentsecure secrets use <alias>", text)
+        self.assertNotIn("virt_openai_should_not_be_written", text)
+        self.assertNotIn("vault://secret-ref-should-not-be-written", text)
+
+    def test_writes_per_run_guidance_under_agentsecure_state(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = write_agent_guidance(temp_dir, "run_test", [])
+
+            self.assertEqual(
+                os.path.join(temp_dir, ".agentsecure", "runs", "run_test", AGENT_GUIDE_FILENAME),
+                path,
+            )
+            self.assertTrue(os.path.exists(path))
+            self.assertEqual(
+                os.path.join(".agentsecure", "runs", "run_test", AGENT_GUIDE_FILENAME),
+                relative_agent_guidance_path(temp_dir, path),
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()