kanibako-cli 1.5.1__tar.gz → 1.6.0.dev24__tar.gz

{kanibako_cli-1.5.1/src/kanibako_cli.egg-info → kanibako_cli-1.6.0.dev24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanibako-cli
-Version: 1.5.1
+Version: 1.6.0.dev24
 Summary: Run AI coding agents in rootless containers with per-project isolation
 Requires-Python: >=3.11
 License-File: LICENSE.md

{kanibako_cli-1.5.1 → kanibako_cli-1.6.0.dev24}/README.md

@@ -751,7 +751,7 @@ Codex CLI, Goose).
 pip install kanibako-target-aider
 
 # Use a specific target
-kanibako box config box.crab=aider
+kanibako box config box.agent=aider
 kanibako start
 ```
 
@@ -809,7 +809,7 @@ All kanibako config files are YAML.
 | `persistence` | `persistent` | Session type (persistent/ephemeral) |
 | `box.image` | `kanibako-oci:latest` | Container rig |
 | `box.shell` | `$KANIBAKO_SHELL` | Shell launched for a no-agent box (`kanibako start` with no agent, `kanibako shell`); resolved `box.shell` → `$KANIBAKO_SHELL` → the image's recorded login shell → `sh` |
-| `box.crab` | (auto-detect) | Agent target plugin |
+| `box.agent` | (auto-detect) | Agent target plugin |
 | `box.share_images` | | Share host images into the box |
 | `group_auth` | `true` | Shared credentials across the group (`true`) vs. per-project (`false`) |
 | `enable_vault` | `true` | Enable vault directories |

{kanibako_cli-1.5.1 → kanibako_cli-1.6.0.dev24}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kanibako-cli"
-version = "1.5.1"
+version = "1.6.0.dev24"
 description = "Run AI coding agents in rootless containers with per-project isolation"
 requires-python = ">=3.11"
 dependencies = ["argcomplete>=3.0", "PyYAML>=6.0"]
@@ -22,9 +22,15 @@ dev = ["pytest>=7.0", "pytest-cov", "mypy", "ruff", "bump2version"]
 where = ["src"]
 
 [tool.setuptools.package-data]
+"kanibako" = ["py.typed"]
 "kanibako.containers" = ["Containerfile.*", "tmux.conf"]
 "kanibako.scripts" = ["*.sh", "kanibako-entry"]
-"kanibako.data" = ["*.yaml"]
+"kanibako.data" = [
+    "*.yaml",
+    "templates/**/*", "templates/**/.*",
+    "templates/.*/**/*", "templates/.*/*",
+    "templates/**/.*/**/*", "templates/**/.*/*",
+]
 
 [tool.ruff]
 target-version = "py311"
@@ -33,6 +39,17 @@ line-length = 99
 [tool.ruff.lint.per-file-ignores]
 "tests/conftest.py" = ["E402"]
 
+[tool.mypy]
+# kanibako is a namespace package split across distributions: the core ships
+# kanibako/ (regular package) while each plugin contributes
+# kanibako/plugins/<agent>/ with no __init__.py in kanibako/plugins/. To let
+# `mypy packages/agent-<agent>/src` assign the full dotted module name (and
+# thus resolve sibling imports like kanibako.plugins.claude.target), point
+# mypy at every src base and enable explicit package bases.
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = "$MYPY_CONFIG_FILE_DIR/src:$MYPY_CONFIG_FILE_DIR/packages/agent-claude/src:$MYPY_CONFIG_FILE_DIR/packages/agent-goose/src:$MYPY_CONFIG_FILE_DIR/packages/agent-codex/src"
+
 [[tool.mypy.overrides]]
 module = ["yaml"]
 ignore_missing_imports = true

{kanibako_cli-1.5.1 → kanibako_cli-1.6.0.dev24}/src/kanibako/__init__.py

@@ -1,3 +1,3 @@
 """kanibako: Run AI coding agents in rootless containers with per-project isolation."""
 
-__version__ = "1.5.1"
+__version__ = "1.6.0.dev24"

kanibako_cli-1.6.0.dev24/src/kanibako/agent_config.py

@@ -0,0 +1,86 @@
+"""Agent YAML configuration: load, write, and resolve per-agent settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from kanibako.config_io import dump_doc, load_doc
+
+# Keys that live directly in the [agent] section as agent identity (not state).
+IDENTITY_KEYS = frozenset({"name", "run_args"})
+
+
+@dataclass
+class AgentConfig:
+    """Per-agent configuration loaded from an agent YAML file.
+
+    Sections:
+      agent  — identity (name, run_args) plus agent-state knobs
+               (model, access, start_mode, autonomous, …)
+      env    — raw env vars injected into container
+      shared — agent-level shared cache paths
+    """
+
+    name: str = ""
+    run_args: list[str] = field(default_factory=list)
+    state: dict[str, str] = field(default_factory=dict)
+    env: dict[str, str] = field(default_factory=dict)
+    shared_caches: dict[str, str] = field(default_factory=dict)
+    tweakcc: dict = field(default_factory=dict)
+
+
+def agents_dir(data_path: Path, paths_agents: str = "agents") -> Path:
+    """Return the agents directory under *data_path*."""
+    return data_path / (paths_agents or "agents")
+
+
+def agent_config_path(
+    data_path: Path, agent_id: str, paths_agents: str = "agents",
+) -> Path:
+    """Return the path to an agent's config file."""
+    return agents_dir(data_path, paths_agents) / f"{agent_id}.yaml"
+
+
+def load_agent_config(path: Path) -> AgentConfig:
+    """Read an agent config file and return an AgentConfig.
+
+    Returns defaults if the file does not exist.
+    """
+    cfg = AgentConfig()
+    if not path.exists():
+        return cfg
+
+    data = load_doc(path)
+
+    agent_sec = data.get("agent", {})
+    cfg.name = str(agent_sec.get("name", ""))
+    raw_args = agent_sec.get("run_args", [])
+    cfg.run_args = [str(a) for a in raw_args] if isinstance(raw_args, list) else []
+
+    cfg.state = {
+        k: str(v) for k, v in agent_sec.items() if k not in IDENTITY_KEYS
+    }
+    cfg.env = {k: str(v) for k, v in data.get("env", {}).items()}
+    cfg.shared_caches = {k: str(v) for k, v in data.get("shared", {}).items()}
+    cfg.tweakcc = dict(data.get("tweakcc", {}))
+
+    return cfg
+
+
+def write_agent_config(path: Path, cfg: AgentConfig) -> None:
+    """Write an AgentConfig to a YAML file."""
+    agent_sec: dict = {
+        "name": cfg.name,
+        "run_args": list(cfg.run_args),
+    }
+    for k, v in cfg.state.items():
+        agent_sec[k] = v
+
+    data: dict = {
+        "agent": agent_sec,
+        "env": dict(cfg.env),
+        "shared": dict(cfg.shared_caches),
+        "tweakcc": dict(cfg.tweakcc),
+    }
+    dump_doc(path, data)

kanibako_cli-1.6.0.dev24/src/kanibako/box_identity.py

@@ -0,0 +1,151 @@
+"""STANDALONE box identity generation (``<random24>_<sanitized,capped leaf>``).
+
+A standalone box is named ``<random24>_<leaf>`` where:
+
+* ``random24`` is 24 bits of randomness (``os.urandom(3)``) encoded as a
+  fixed-width, lowercased base32 token (no padding) — always 5 characters.
+* ``leaf`` is the project-root basename, sanitized so only portable filename
+  characters survive (``[^A-Za-z0-9._-]`` → ``_``), capped at 32 characters,
+  with an empty leaf falling back to ``"box"``.
+
+The pieces are joined with ``_``.  Because the random prefix can collide with
+an already-registered standalone box name (design-review D-M13), the generator
+regenerates the random component (bounded retries) until the *whole* name is
+unique within a caller-supplied ``existing`` set.
+
+This module is pure (modulo ``os.urandom``) and side-effect free so the
+sanitize/cap/collision-regen logic is directly unit-testable.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import re
+from pathlib import Path
+
+from kanibako.errors import ProjectError
+
+# Maximum length of the sanitized leaf component.
+_LEAF_CAP = 32
+# Fallback leaf when the project basename sanitizes to empty.
+_EMPTY_LEAF_FALLBACK = "box"
+# Characters that are NOT replaced during sanitization.
+_SAFE_CHAR_RE = re.compile(r"[^A-Za-z0-9._-]")
+# Bound on collision-regeneration attempts before giving up.
+_MAX_REGEN_ATTEMPTS = 1000
+
+# A canonical standalone box name is ``<random24>_<leaf>`` where the random
+# prefix is exactly 5 lowercase base32 chars and the leaf is 1-32 chars drawn
+# from the sanitized, *lowercased* alphabet (see :func:`sanitize_cap`).  This
+# is the verbatim shape the generator emits, so it is also what a user may
+# assert by passing a fully-formed ``--name``.
+_CANONICAL_NAME_RE = re.compile(r"^[a-z2-7]{5}_[a-z0-9._-]{1,32}$")
+
+
+def random24() -> str:
+    """Return a 24-bit random token as a fixed-width lowercase base32 string.
+
+    24 bits encode to exactly 5 base32 characters (with the trailing ``=``
+    padding stripped), so every token is the same width.  Lowercased for
+    container/path friendliness.
+    """
+    raw = os.urandom(3)  # 3 bytes == 24 bits
+    return base64.b32encode(raw).decode("ascii").rstrip("=").lower()
+
+
+def sanitize_cap(leaf: str) -> str:
+    """Sanitize, lowercase, and cap a project-basename *leaf* for a box name.
+
+    Non-portable characters (anything outside ``[A-Za-z0-9._-]``) become ``_``;
+    the result is lowercased (every box name is lowercase) and capped at
+    :data:`_LEAF_CAP` characters.  An empty result (e.g. an empty or all-illegal
+    basename) falls back to ``"box"``.
+    """
+    sanitized = _SAFE_CHAR_RE.sub("_", leaf).lower()[:_LEAF_CAP]
+    return sanitized or _EMPTY_LEAF_FALLBACK
+
+
+def is_canonical_standalone_name(name: str) -> bool:
+    """True when *name* matches the canonical ``<random24>_<leaf>`` shape.
+
+    The prefix must be exactly 5 lowercase base32 chars (``[a-z2-7]``) and the
+    leaf 1-32 chars of ``[a-z0-9._-]`` (lowercase, matching :func:`sanitize_cap`).
+    An over-long or illegal-char leaf, or a wrong-width prefix, fails the match.
+    The check is case-sensitive: callers lowercase a supplied name first.
+    """
+    return _CANONICAL_NAME_RE.match(name) is not None
+
+
+def _generate_with_leaf(leaf: str, existing: set[str]) -> str:
+    """Build ``<random24>_<leaf>`` with whole-name collision regen.
+
+    *leaf* must already be sanitized (see :func:`sanitize_cap`).  Regenerates
+    the random prefix (bounded retries) until the whole name is unique within
+    *existing*.  Shared by :func:`make_standalone_box_name` (leaf from the root
+    basename) and :func:`resolve_standalone_name` (leaf from a supplied string).
+
+    Raises :class:`RuntimeError` if a unique name cannot be found within
+    :data:`_MAX_REGEN_ATTEMPTS` attempts.
+    """
+    for _ in range(_MAX_REGEN_ATTEMPTS):
+        name = f"{random24()}_{leaf}"
+        if name not in existing:
+            return name
+    raise RuntimeError(
+        "Could not generate a unique standalone box name after "
+        f"{_MAX_REGEN_ATTEMPTS} attempts."
+    )
+
+
+def make_standalone_box_name(root: Path, existing: set[str]) -> str:
+    """Generate a unique standalone box name for project *root*.
+
+    Builds ``<random24>_<sanitize_cap(root.name)>`` and, if that whole name is
+    already in *existing*, regenerates the random prefix (bounded retries) until
+    the name is unique.  *existing* is the set of standalone box names currently
+    registered (see ``registry.standalone``).
+
+    Raises :class:`RuntimeError` if a unique name cannot be found within
+    :data:`_MAX_REGEN_ATTEMPTS` attempts (effectively impossible with a sane
+    ``existing`` set; the bound guards against a degenerate caller).
+    """
+    return _generate_with_leaf(sanitize_cap(root.name), existing)
+
+
+def resolve_standalone_name(
+    root: Path, supplied: str, existing: set[str],
+) -> str:
+    """Resolve the standalone box name for *root* given a user *supplied* name.
+
+    Pure (modulo ``os.urandom``) so it is directly unit-testable.  Branches:
+
+    1. *supplied* empty → :func:`make_standalone_box_name` (fresh prefix +
+       sanitized ``root.name`` leaf, whole-name collision regen).
+    2. Otherwise lowercase *supplied*, then:
+
+       * If it does NOT match the canonical ``<random24>_<leaf>`` shape (see
+         :func:`is_canonical_standalone_name`) → treat the WHOLE supplied string
+         as a raw leaf: ``<fresh-random>_<sanitize_cap(supplied)>`` with
+         collision regen.  (An over-long / illegal name lands here.)
+       * If it DOES match → the user is asserting a full canonical id verbatim.
+         If it is free in *existing* → return it as-is; if taken → raise
+         :class:`~kanibako.errors.ProjectError`.
+    """
+    if not supplied:
+        return make_standalone_box_name(root, existing)
+
+    supplied = supplied.lower()
+
+    if not is_canonical_standalone_name(supplied):
+        # Not a canonical id: use the whole supplied string as the leaf source.
+        return _generate_with_leaf(sanitize_cap(supplied), existing)
+
+    # A verbatim canonical id: honor it if free, else refuse with guidance.
+    if supplied in existing:
+        prefix = supplied.partition("_")[0]
+        raise ProjectError(
+            f"already a box with that name '{supplied}' — try without the "
+            f"'{prefix}_' prefix to generate a fresh one"
+        )
+    return supplied

kanibako_cli-1.6.0.dev24/src/kanibako/channels.py

@@ -0,0 +1,253 @@
+"""Channel path resolution + per-instance partition addressing (PURE helpers).
+
+Phase 6 (sub-step 6a) of the 1.6.0 config/settings revamp.  This module derives
+the host-side channel paths from an already-resolved :class:`~kanibako.paths.
+ProjectPaths` (``proj``) + :class:`~kanibako.paths.StandardPaths` (``std``).  It
+is **pure derivation only** — it computes paths, it does NOT create directories,
+touch launch mounts, or change any behavior.  The bind production / mkdir /
+file-seeding live in sub-step 6b.
+
+Two channel scopes (TARGET §1, §2c, §2f):
+
+* **system scope** — five type roots under ``@system.channels`` (commons, chat,
+  broadcast, mailboxes, share).  The instance-owned types (mailboxes, share) are
+  *partitioned* by the workset-name token: ``mailboxes/<ws>`` and ``share/<ws>``
+  where ``<ws>`` is ``__PRIMARY__`` | ``<named>`` | ``__STANDALONE__``.  These
+  partition roots apply to EVERY mode (standalone included).
+* **workset scope** — three type roots under ``@workset.meta.root/channels``
+  (commons, chat, share).  These exist for the PRIMARY and NAMED modes ONLY;
+  standalone has no workset-local channels (its ``workset.channels`` is
+  ``<None>`` per the TARGET).
+
+The per-instance partition ADDRESSES (``box.meta.{inbox,share_global,
+share_workset}``) are this box's own mailbox/share dirs *within* the partitioned
+roots — derived from the workset-name token + the box name.
+
+⚑ The workset-name token and the workset root are NOT carried verbatim on
+``ProjectPaths`` (the legacy comms block used only ``proj.name``).  Per the
+design-review A8 resolution we derive them HERE from ``proj.mode`` + ``proj.
+group`` rather than widening the resolver's public shape: PRIMARY roots at
+``@system.primary_workset`` with token ``__PRIMARY__``; NAMED roots at
+``proj.group.root`` with token ``proj.group.name``; STANDALONE roots at
+``proj.project_path`` with token ``__STANDALONE__``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # avoid an import cycle (paths.py would import this later)
+    from kanibako.paths import ProjectPaths, StandardPaths
+
+
+# Reserved workset-name tokens for the system-scope partition key.  A named
+# workset may not use either (Phase 5 reserves them at create time, 5e); they
+# stand for the PRIMARY and STANDALONE pseudo-worksets.
+WS_TOKEN_PRIMARY = "__PRIMARY__"
+WS_TOKEN_STANDALONE = "__STANDALONE__"
+
+
+@dataclass(frozen=True)
+class SystemPartition:
+    """The per-workset SYSTEM-scope partition roots (keyed by the ws token).
+
+    ``mailboxes`` == ``@system.channels.mailboxes/<ws>`` and ``share`` ==
+    ``@system.channels.share/<ws>``.  These are the *parents* under which each
+    box gets its own ``<box>`` subdir (see :func:`box_channel_addresses`).
+    """
+
+    ws_token: str
+    mailboxes: Path
+    share: Path
+
+
+@dataclass(frozen=True)
+class WorksetChannels:
+    """The workset-local channel roots (PRIMARY/NAMED only).
+
+    ``@workset.channels = @workset.meta.root/channels`` with ``commons``,
+    ``chat`` (+ the reserved ``broadcast.md`` / default ``general.md`` files
+    inside it), and ``share`` (per-box subdirs are ``box.meta.share_workset``).
+    """
+
+    root: Path
+    commons: Path
+    chat: Path
+    chat_general: Path
+    chat_broadcast: Path
+    share: Path
+
+
+@dataclass(frozen=True)
+class BoxChannelAddresses:
+    """This box's own partition ADDRESSES (TARGET §2c ``box.meta.*``).
+
+    * ``inbox`` == ``@system.channels.mailboxes/<ws>/<box>`` — this box's own
+      mailbox dir (also surfaced in-box at ``~/channels/inbox``).
+    * ``share_global`` == ``@system.channels.share/<ws>/<box>`` — this box's own
+      system-scope publication dir.
+    * ``share_workset`` == ``@workset.channels.share/<box>`` — this box's own
+      workset-scope publication dir; ``None`` for standalone (no workset-local
+      channels).
+    """
+
+    ws_token: str
+    box_name: str
+    inbox: Path
+    share_global: Path
+    share_workset: Path | None
+
+
+@dataclass(frozen=True)
+class OwnPartition:
+    """This box's OWN system-scope partition dirs (mailbox + share_global).
+
+    ``mailbox`` == ``@system.channels.mailboxes/<ws>/<box>`` (this box's inbox
+    source dir) and ``share_global`` == ``@system.channels.share/<ws>/<box>``
+    (this box's system-scope publication dir).  Used by the move/convert
+    relocation (6d), which addresses the partition by raw ``(ws_token, box)``
+    rather than a fully-resolved :class:`ProjectPaths`.
+    """
+
+    ws_token: str
+    box_name: str
+    mailbox: Path
+    share_global: Path
+
+
+def own_partition_dirs(
+    std: StandardPaths, ws_token: str, box_name: str
+) -> OwnPartition:
+    """Derive a box's OWN system-scope partition dirs from ``(ws_token, box)``.
+
+    The lower-level primitive behind :func:`box_channel_addresses` — it takes the
+    workset-name token + box name directly (no ``ProjectPaths``), so the lifecycle
+    relocation can compute BOTH the OLD and the NEW partition for a box being
+    moved/converted.  Mirrors :func:`system_partition` + the ``box.meta.{inbox,
+    share_global}`` joins (TARGET §2c).
+    """
+    part = system_partition(std, ws_token)
+    return OwnPartition(
+        ws_token=ws_token,
+        box_name=box_name,
+        mailbox=part.mailboxes / box_name,
+        share_global=part.share / box_name,
+    )
+
+
+def workset_name_token(proj: ProjectPaths) -> str:
+    """Return the workset-name token for *proj* (the system partition key).
+
+    ``__PRIMARY__`` for PRIMARY mode, the named workset's name for NAMED mode,
+    ``__STANDALONE__`` for STANDALONE mode.  Derived from ``proj.mode`` +
+    ``proj.group`` (A8) rather than read off a dedicated field.
+    """
+    # Lazy import keeps this module free of an import cycle with paths.py.
+    from kanibako.paths import BoxMode
+
+    if proj.mode is BoxMode.primary:
+        return WS_TOKEN_PRIMARY
+    if proj.mode is BoxMode.standalone:
+        return WS_TOKEN_STANDALONE
+    # NAMED: the partition key is the named workset's name.
+    if proj.group is None or not proj.group.name:
+        raise ValueError(
+            "NAMED box is missing its workset group/name; cannot derive the "
+            "channel partition token."
+        )
+    return proj.group.name
+
+
+def workset_root(proj: ProjectPaths, std: StandardPaths) -> Path:
+    """Return ``@workset.meta.root`` for *proj*.
+
+    PRIMARY → ``@system.primary_workset``; NAMED → the named workset root
+    (``proj.group.root``); STANDALONE → the project dir itself
+    (``proj.project_path``).
+    """
+    from kanibako.paths import BoxMode
+
+    if proj.mode is BoxMode.primary:
+        return std.primary_workset
+    if proj.mode is BoxMode.standalone:
+        return proj.project_path
+    if proj.group is None:
+        raise ValueError(
+            "NAMED box is missing its workset group; cannot derive the workset "
+            "root."
+        )
+    return proj.group.root
+
+
+def has_workset_channels(proj: ProjectPaths) -> bool:
+    """True iff *proj* gets workset-local channels (PRIMARY/NAMED, not standalone).
+
+    Standalone omits ``~/channels/workset/*`` (no workset-local channels); its
+    system-scope partition (mailboxes/share_global) still applies (A10).
+    """
+    from kanibako.paths import BoxMode
+
+    return proj.mode is not BoxMode.standalone
+
+
+def system_partition(std: StandardPaths, ws_token: str) -> SystemPartition:
+    """Derive the SYSTEM-scope per-workset partition roots for *ws_token*.
+
+    ``mailboxes/<ws>`` and ``share/<ws>`` under the resolved system channels
+    skeleton.  Applies to EVERY mode — do NOT gate this off the workset-local
+    channels (D-M9): standalone still has a ``__STANDALONE__`` partition.
+    """
+    return SystemPartition(
+        ws_token=ws_token,
+        mailboxes=std.channels_mailboxes / ws_token,
+        share=std.channels_share / ws_token,
+    )
+
+
+def workset_channel_paths(
+    proj: ProjectPaths, std: StandardPaths
+) -> WorksetChannels | None:
+    """Derive the WORKSET-local channel roots for *proj* (PRIMARY/NAMED only).
+
+    Returns ``None`` for standalone (no workset-local channels).  Rooted at
+    ``@workset.meta.root/channels`` (A3 — a derived helper, NOT new fields on
+    ``ProjectPaths``).
+    """
+    if not has_workset_channels(proj):
+        return None
+    root = workset_root(proj, std) / "channels"
+    chat = root / "chat"
+    return WorksetChannels(
+        root=root,
+        commons=root / "commons",
+        chat=chat,
+        chat_general=chat / "general.md",
+        chat_broadcast=chat / "broadcast.md",
+        share=root / "share",
+    )
+
+
+def box_channel_addresses(
+    proj: ProjectPaths, std: StandardPaths
+) -> BoxChannelAddresses:
+    """Derive this box's own partition addresses (``box.meta.*``) for *proj*.
+
+    ``inbox`` / ``share_global`` always resolve (system-scope, every mode);
+    ``share_workset`` is ``None`` for standalone.  *proj.name* is the box name.
+    """
+    if not proj.name:
+        raise ValueError(
+            "box has no name; cannot derive its channel partition addresses."
+        )
+    ws_token = workset_name_token(proj)
+    part = system_partition(std, ws_token)
+    wch = workset_channel_paths(proj, std)
+    return BoxChannelAddresses(
+        ws_token=ws_token,
+        box_name=proj.name,
+        inbox=part.mailboxes / proj.name,
+        share_global=part.share / proj.name,
+        share_workset=(wch.share / proj.name) if wch is not None else None,
+    )