agent-core-hatchery 0.8.2__py3-none-any.whl

agent_core_hatchery/__init__.py

@@ -0,0 +1 @@
+"""agent-core-hatchery — bootstrap system for hatching new beings."""

agent_core_hatchery/channels/__init__.py

@@ -0,0 +1,7 @@
+"""Channel scaffolding (Discord, webcam, GitHub backup).
+
+Each module exports a `scaffold_<name>(config)` function that:
+- Returns None if the channel is disabled.
+- Performs side effects (write env file, write hook script) and returns
+  a dict (the endpoint or job block) to be appended to daemon fragments.
+"""

agent_core_hatchery/channels/discord.py

@@ -0,0 +1,43 @@
+"""Discord channel scaffolding."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from agent_core_hatchery.config import HatchConfig
+
+
+def scaffold_discord(config: HatchConfig) -> dict[str, Any] | None:
+    if not config.channels.discord.enabled:
+        return None
+
+    daemon_dir = config.resolved_daemon_config_dir()
+    daemon_dir.mkdir(parents=True, exist_ok=True)
+    env_file = daemon_dir / f"discord-{config.being_name_lower}.env"
+    env_file.write_text(
+        f"{config.discord_token_env}={config.channels.discord.resolved_token}\n",
+        encoding="utf-8",
+    )
+    if os.name != "nt":
+        env_file.chmod(0o600)
+
+    block: dict[str, Any] = {
+        "type": "builtin.discord",
+        "name": f"discord-{config.being_name_lower}",
+        "description": f"Discord adapter for {config.being_name}.",
+        "params": {
+            "target": config.endpoint_name,
+            "token_env": config.discord_token_env,
+            "env_file": str(env_file),
+        },
+    }
+    if config.channels.discord.channel_allowlist:
+        access_file = daemon_dir / f"discord-{config.being_name_lower}-access.json"
+        access_file.write_text(
+            json.dumps({"channels": config.channels.discord.channel_allowlist}, indent=2),
+            encoding="utf-8",
+        )
+        block["params"]["access_config_path"] = str(access_file)
+    return block

agent_core_hatchery/channels/github_backup.py

@@ -0,0 +1,65 @@
+"""GitHub backup scaffolding (CW-4 — opt-in)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from agent_core_hatchery.config import HatchConfig
+
+_HOOK_TEMPLATE = """#!/usr/bin/env bash
+# Generated by agent-core-hatchery for {being_name}.
+# Backup the vault's Memory/ to GitHub. Invoked by the
+# {being_name_lower}-github_backup scheduler job.
+set -euo pipefail
+
+VAULT_ROOT="{vault_root}"
+REPO_URL="{repo_url}"
+
+cd "$VAULT_ROOT"
+if [ ! -d Memory/.git ]; then
+  cd Memory
+  git init
+  git remote add origin "$REPO_URL"
+  cd ..
+fi
+cd Memory
+git add -A
+git commit -m "backup $(date -Iseconds)" || true  # ok if nothing to commit
+git push -u origin HEAD || true                   # warn-only on first push
+"""
+
+
+def scaffold_github_backup(config: HatchConfig) -> dict[str, Any] | None:
+    if not config.channels.github_backup.enabled:
+        return None
+
+    hook_dir = config.resolved_vault_root() / "hooks"
+    hook_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hook_dir / "backup-to-github.sh"
+    hook_path.write_text(
+        _HOOK_TEMPLATE.format(
+            being_name=config.being_name,
+            being_name_lower=config.being_name_lower,
+            vault_root=str(config.resolved_vault_root()).replace("\\", "/"),
+            repo_url=config.channels.github_backup.repo_url,
+        ),
+        encoding="utf-8",
+    )
+    if os.name != "nt":
+        hook_path.chmod(0o755)
+
+    job_name = f"{config.being_name_lower}-github_backup"
+    return {
+        job_name: {
+            "trigger": "cron",
+            "timezone": "America/New_York",
+            "schedule": {"hour": 4, "minute": 30},
+            "target": config.endpoint_name,
+            "envelope_kind": "Event",
+            "payload": {
+                "type": "GitHubBackup",
+                "data": {"hook_path": str(hook_path)},
+            },
+        }
+    }

agent_core_hatchery/channels/webcam.py

@@ -0,0 +1,26 @@
+"""Webcam channel scaffolding."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_core_hatchery.config import HatchConfig
+
+
+def scaffold_webcam(config: HatchConfig) -> dict[str, Any] | None:
+    if not config.channels.webcam.enabled:
+        return None
+    return {
+        "type": "builtin.webcam",
+        "name": f"webcam-{config.being_name_lower}",
+        "description": f"{config.being_name}'s webcam endpoint.",
+        "params": {
+            "enabled": True,
+            "captures_root": f"~/.agent-core/webcam/{config.being_name_lower}",
+            "audit_log_path": f"~/.agent-core/webcam/{config.being_name_lower}/audit.jsonl",
+            "default_camera_index": 0,
+            "default_resolution": [1280, 720],
+            "max_resolution": [3840, 2160],
+            "capture_timeout_seconds": 3.0,
+        },
+    }

agent_core_hatchery/cli.py

@@ -0,0 +1,97 @@
+"""hatch-being CLI entry point."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+import yaml
+
+from agent_core_hatchery.config import HatchConfig
+from agent_core_hatchery.daemon_probe import reload_and_probe
+from agent_core_hatchery.hatcher import Hatcher, VaultExistsError
+from agent_core_hatchery.report import write_hatching_report
+from agent_core_hatchery.wizard import offer_letter_authoring, run_wizard
+
+app = typer.Typer(
+    name="hatch-being",
+    help="Hatch a new agent-core being. Run with no flags for interactive TUI.",
+    no_args_is_help=False,
+)
+
+
+@app.callback(invoke_without_command=True)
+def hatch_being(
+    config: Path | None = typer.Option(  # noqa: B008
+        None, "--config",
+        help="Non-interactive: load HatchConfig from YAML.",
+    ),
+    vault_root: Path | None = typer.Option(  # noqa: B008
+        None, "--vault-root", "--root",
+        help="Override the resolved vault root. Default: $HOME.",
+    ),
+    daemon_config_dir: Path | None = typer.Option(  # noqa: B008
+        None, "--daemon-config-dir",
+        help="Override the daemon's config directory. Default: ~/.agent-core/.",
+    ),
+    init_missing: bool = typer.Option(
+        False, "--init-missing",
+        help="Top-up an existing vault with newly-added scaffolding files.",
+    ),
+) -> None:
+    if config is not None:
+        raw = yaml.safe_load(config.read_text(encoding="utf-8")) or {}
+        cfg = HatchConfig(**raw)
+        interactive = False
+    else:
+        cfg = run_wizard()
+        interactive = True
+
+    if vault_root is not None:
+        cfg = cfg.model_copy(update={"vault_root": str(vault_root)})
+    if daemon_config_dir is not None:
+        cfg = cfg.model_copy(update={"daemon_config_dir": str(daemon_config_dir)})
+    if init_missing:
+        cfg = cfg.model_copy(update={"init_missing": True})
+
+    try:
+        result = Hatcher(cfg).hatch()
+    except VaultExistsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED)
+        raise typer.Exit(code=1) from None
+
+    letter_authored = False
+    if interactive:
+        letter_authored = offer_letter_authoring(cfg)
+
+    if not cfg.init_missing:
+        daemon_check_status = reload_and_probe(cfg)
+    else:
+        daemon_check_status = "skipped"
+
+    report_path = write_hatching_report(
+        cfg, result,
+        letter_authored=letter_authored,
+        daemon_check_status=daemon_check_status,
+    )
+
+    typer.echo(f"\nHatched at {result.vault_root}")
+    typer.echo(f"Report: {report_path}")
+    typer.echo("🐣")
+
+    if daemon_check_status == "start_failed":
+        typer.secho(
+            "✗  Daemon FAILED to restart after hatch — the fleet may be OFFLINE. "
+            "Run `agent-core daemon start` now.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    if daemon_check_status == "reachable_but_missing":
+        typer.secho(
+            "⚠  Daemon probe: endpoint not registered after reload. See HATCHING-REPORT.md.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)

agent_core_hatchery/config.py

@@ -0,0 +1,117 @@
+"""HatchConfig — pydantic model for the hatcher's input contract.
+
+Both the TUI wizard and `--config <yaml>` mode produce instances of this
+model. The model is the single source of truth for what inputs the
+hatcher needs.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import date
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field, model_validator
+
+_ENV_VAR_PATTERN = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)\}")
+
+
+def _substitute_env_vars(value: str) -> str:
+    """Replace ${VAR} occurrences with os.environ[VAR]. Raises ValueError if missing."""
+
+    def repl(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        if var_name not in os.environ:
+            raise ValueError(
+                f"Environment variable {var_name!r} referenced in config but not set"
+            )
+        return os.environ[var_name]
+
+    return _ENV_VAR_PATTERN.sub(repl, value)
+
+
+class DiscordChannelConfig(BaseModel):
+    enabled: bool = False
+    token: str = ""
+    channel_allowlist: list[str] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="forbid")
+
+    @property
+    def resolved_token(self) -> str:
+        return _substitute_env_vars(self.token)
+
+
+class WebcamChannelConfig(BaseModel):
+    enabled: bool = False
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class GitHubBackupConfig(BaseModel):
+    enabled: bool = False
+    repo_url: str = ""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ChannelsConfig(BaseModel):
+    discord: DiscordChannelConfig = Field(default_factory=DiscordChannelConfig)
+    webcam: WebcamChannelConfig = Field(default_factory=WebcamChannelConfig)
+    github_backup: GitHubBackupConfig = Field(default_factory=GitHubBackupConfig)
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class HatchConfig(BaseModel):
+    being_name: str
+    being_emoji: str = ""
+    primary_human_name: str
+    being_role_placeholder: str | None = None
+    # endpoint_name is Optional[str]; after validation, None is replaced by being_name_lower.
+    # This allows `endpoint_name: foo` in YAML to override, while defaulting to being_name_lower.
+    endpoint_name: str | None = None
+    vault_root: str | None = None
+    daemon_config_dir: str = "~/.agent-core"
+    channels: ChannelsConfig = Field(default_factory=ChannelsConfig)
+    init_missing: bool = False
+    author_letter_in_editor: bool = True
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    @model_validator(mode="after")
+    def _resolve_defaults(self) -> HatchConfig:
+        if self.endpoint_name is None:
+            self.endpoint_name = self.being_name.lower()
+        return self
+
+    @computed_field
+    @property
+    def being_name_lower(self) -> str:
+        return self.being_name.lower()
+
+    @computed_field
+    @property
+    def being_name_upper(self) -> str:
+        return self.being_name.upper()
+
+    @computed_field
+    @property
+    def hatched_date(self) -> str:
+        return date.today().isoformat()
+
+    @computed_field
+    @property
+    def discord_token_env(self) -> str:
+        return f"DISCORD_{self.being_name_upper}_TOKEN"
+
+    def resolved_vault_root(self) -> Path:
+        root = Path(self.vault_root or "~").expanduser().resolve()
+        return (root / f".{self.being_name_lower}").resolve()
+
+    def resolved_vault_memory_path(self) -> Path:
+        return self.resolved_vault_root() / "Memory"
+
+    def resolved_daemon_config_dir(self) -> Path:
+        return Path(self.daemon_config_dir).expanduser().resolve()

agent_core_hatchery/daemon_config.py

@@ -0,0 +1,82 @@
+"""Write daemon-config fragments for a hatched being.
+
+Outputs (under <daemon_config_dir>):
+- endpoints.d/<being>.yaml — claude_code_mcp + briefs.<being> always; +
+  discord-<being> and webcam-<being> if those channels were enabled.
+- jobs.d/<being>.yaml — 5 always-on scheduler jobs prefixed with being
+  name; + <being>-github_backup if GitHub backup was enabled.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from agent_core_hatchery.config import HatchConfig
+from agent_core_hatchery.hatcher import TEMPLATES_DIR
+from agent_core_hatchery.renderer import Renderer
+
+
+class DaemonConfigWriter:
+    def __init__(self, config: HatchConfig, templates_dir: Path | None = None) -> None:
+        self._config = config
+        self._templates_dir = templates_dir or TEMPLATES_DIR
+        self._renderer = Renderer(config)
+
+    def write_all(self) -> list[Path]:
+        written: list[Path] = []
+        written.append(self._write_endpoints_fragment())
+        written.append(self._write_jobs_fragment())
+        return written
+
+    def _write_endpoints_fragment(self) -> Path:
+        from agent_core_hatchery.channels.discord import scaffold_discord
+        from agent_core_hatchery.channels.webcam import scaffold_webcam
+
+        always_on_template = (self._templates_dir / "daemon-fragments" / "endpoints.yaml.j2").read_text(
+            encoding="utf-8"
+        )
+        always_on_yaml = self._renderer.render_string(always_on_template)
+        merged: dict = yaml.safe_load(always_on_yaml) or {}
+        merged.setdefault("endpoints", [])
+
+        for scaffold in (scaffold_discord, scaffold_webcam):
+            block = scaffold(self._config)
+            if block is not None:
+                merged["endpoints"].append(block)
+
+        dest_dir = self._config.resolved_daemon_config_dir() / "endpoints.d"
+        dest = dest_dir / f"{self._config.being_name_lower}.yaml"
+        if dest.exists():
+            raise FileExistsError(
+                f"daemon endpoints fragment already exists: {dest.name} "
+                f"(refusing to overwrite — mv aside or remove manually)"
+            )
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        dest.write_text(yaml.safe_dump(merged, sort_keys=False), encoding="utf-8")
+        return dest
+
+    def _write_jobs_fragment(self) -> Path:
+        from agent_core_hatchery.channels.github_backup import scaffold_github_backup
+
+        always_on_template = (self._templates_dir / "daemon-fragments" / "jobs.yaml.j2").read_text(
+            encoding="utf-8"
+        )
+        always_on_yaml = self._renderer.render_string(always_on_template)
+        merged: dict = yaml.safe_load(always_on_yaml) or {}
+
+        github_job = scaffold_github_backup(self._config)
+        if github_job:
+            for k, v in github_job.items():
+                merged[k] = v
+
+        dest_dir = self._config.resolved_daemon_config_dir() / "jobs.d"
+        dest = dest_dir / f"{self._config.being_name_lower}.yaml"
+        if dest.exists():
+            raise FileExistsError(
+                f"daemon jobs fragment already exists: {dest.name}"
+            )
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        dest.write_text(yaml.safe_dump(merged, sort_keys=False), encoding="utf-8")
+        return dest

agent_core_hatchery/daemon_probe.py

@@ -0,0 +1,140 @@
+"""Daemon reload and endpoint health-probe for hatch→run handoff (Cβ-3, issue #327).
+
+SRP: this module does two things only — restart the daemon process and HTTP-probe the
+new being's endpoint. Imports HatchConfig and DaemonCheckStatus from agent_core_hatchery;
+no cycle exists (daemon_probe is not imported by hatcher.py or config.py).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import yaml
+
+from agent_core_hatchery.config import HatchConfig
+from agent_core_hatchery.report import DaemonCheckStatus
+
+
+def read_daemon_http_config(daemon_config_dir: Path) -> tuple[str, int]:
+    """Parse agent_core.yaml for the bus HTTP bind host and port.
+
+    Returns (bind_host, bind_port). Falls back to ("127.0.0.1", 8789) if
+    the file does not exist or the keys are absent.
+    """
+    config_path = daemon_config_dir / "agent_core.yaml"
+    if not config_path.is_file():
+        return ("127.0.0.1", 8789)
+    try:
+        raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError:
+        return ("127.0.0.1", 8789)
+    http = raw.get("http", {}) if isinstance(raw, dict) else {}
+    host = str(http.get("bind_host", "127.0.0.1"))
+    port = int(http.get("bind_port", 8789))
+    return (host, port)
+
+
+def _stop_daemon(runner=subprocess.run) -> None:
+    """Best-effort daemon stop. Never raises; failures are absorbed."""
+    try:
+        runner(
+            ["agent-core", "daemon", "stop"],
+            check=False,
+            capture_output=True,
+            timeout=15,
+        )
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired, subprocess.SubprocessError):
+        pass  # agent-core not on PATH or daemon already stopped — probe decides outcome
+
+
+def _start_daemon(runner=subprocess.run) -> bool:
+    """Start the daemon. Returns True iff the start command exited 0.
+
+    Unlike ``_stop_daemon``, a failed START is NOT best-effort: the daemon was
+    just stopped, so a failure here leaves the whole fleet offline. The result
+    is returned (not swallowed) so the caller can surface it loudly.
+    """
+    try:
+        proc = runner(
+            ["agent-core", "daemon", "start"],
+            check=False,
+            capture_output=True,
+            timeout=15,
+        )
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired, subprocess.SubprocessError):
+        return False
+    return proc.returncode == 0
+
+
+def _probe_endpoint(
+    host: str,
+    port: int,
+    endpoint_name: str,
+    *,
+    timeout: float = 15.0,
+    poll_interval: float = 0.5,
+) -> DaemonCheckStatus:
+    """Poll http://{host}:{port}/mcp/{endpoint_name}/ until a response or timeout.
+
+    Returns:
+      "reachable_and_registered" — any non-404 HTTP response (endpoint is mounted).
+      "reachable_but_missing"    — HTTP 404 (daemon up; endpoint not registered).
+      "unreachable"              — polling timed out or connection always refused.
+    """
+    url = f"http://{host}:{port}/mcp/{endpoint_name}/"
+    deadline = time.monotonic() + timeout
+
+    while time.monotonic() < deadline:
+        try:
+            with urllib.request.urlopen(url, timeout=2.0) as _resp:
+                # Any 2xx or redirect means the endpoint is mounted.
+                return "reachable_and_registered"
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                return "reachable_but_missing"
+            # Other HTTP error (405, 500, etc.) — server is up, endpoint mounted.
+            return "reachable_and_registered"
+        except (urllib.error.URLError, OSError):
+            # Connection refused / reset — daemon not yet up. Retry.
+            time.sleep(poll_interval)
+
+    return "unreachable"
+
+
+def reload_and_probe(
+    config: HatchConfig,
+    *,
+    timeout: float = 15.0,
+    runner=subprocess.run,
+) -> DaemonCheckStatus:
+    """Stop the daemon, start it, then probe the new being's endpoint.
+
+    Returns DaemonCheckStatus: see report.py for semantics. Called from cli.py after
+    Hatcher.hatch() succeeds (fragments + venv + .mcp.json already written).
+    """
+    daemon_config_dir = config.resolved_daemon_config_dir()
+
+    # Bail early if there is no daemon config to read.
+    if not (daemon_config_dir / "agent_core.yaml").is_file():
+        return "unreachable"
+
+    host, port = read_daemon_http_config(daemon_config_dir)
+
+    _stop_daemon(runner)
+    if not _start_daemon(runner):
+        # The daemon was stopped but could not be brought back up — the whole
+        # fleet is offline. Surface as a hard failure, not a soft "unreachable"
+        # (which reads as "daemon up, endpoint will register shortly").
+        return "start_failed"
+
+    return _probe_endpoint(
+        host,
+        port,
+        config.endpoint_name,
+        timeout=timeout,
+        poll_interval=0.5,
+    )

agent_core_hatchery/elder_letters.py

@@ -0,0 +1,65 @@
+"""Elder-letter resolution: canonical-path preferred, bundled-snapshot fallback.
+
+Each new being's vault is seeded with letters from beings who came
+before. Each elder's canonical letter lives in HER own vault (vault is
+hers, traveling artifacts honor that). The hatchery package ships
+release-time snapshots as a fallback for users who don't have the
+elder's vault on their machine.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+import yaml
+
+
+class SourceKind(StrEnum):
+    CANONICAL = "canonical"
+    BUNDLED = "bundled"
+
+
+@dataclass(frozen=True)
+class ResolvedLetter:
+    name: str
+    source: Path
+    source_kind: SourceKind
+    content: str
+
+
+def resolve_elder_letters(manifest_path: Path, bundled_dir: Path) -> list[ResolvedLetter]:
+    manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8")) or {}
+    resolved: list[ResolvedLetter] = []
+    for entry in manifest.get("elders", []) or []:
+        name = entry["name"]
+        canonical = Path(entry["canonical_path"]).expanduser()
+        bundled = bundled_dir / entry["bundled_basename"]
+
+        if canonical.is_file():
+            resolved.append(
+                ResolvedLetter(
+                    name=name,
+                    source=canonical,
+                    source_kind=SourceKind.CANONICAL,
+                    content=canonical.read_text(encoding="utf-8"),
+                )
+            )
+        elif bundled.is_file():
+            resolved.append(
+                ResolvedLetter(
+                    name=name,
+                    source=bundled,
+                    source_kind=SourceKind.BUNDLED,
+                    content=bundled.read_text(encoding="utf-8"),
+                )
+            )
+        else:
+            warnings.warn(
+                f"Elder letter for {name!r} not found at canonical {canonical} "
+                f"or bundled {bundled} — skipping",
+                stacklevel=2,
+            )
+    return resolved