jvagent 0.1.1__py3-none-any.whl

jvagent/__init__.py

@@ -0,0 +1,35 @@
+"""jvagent - Agentive Platform built on jvspatial.
+
+Two supported usage modes:
+
+* **Standalone server** (CLI) — ``jvagent run`` boots jvagent's own
+  jvspatial ``Server`` and HTTP surface. The default for new apps.
+* **Embedded library** — host an existing jvspatial app (e.g. another
+  product also built on jvspatial) calls :mod:`jvagent.embed` to mount
+  jvagent's runtime in-process, sharing the host's database and
+  authentication. See :mod:`jvagent.embed` for the supported surface.
+
+Public, semver-tracked exports live here. Anything reached via
+``jvagent.<internal_module>`` is implementation detail and may break
+between minor versions.
+"""
+
+# Install the Logger subclass that accepts ``details=`` as a kwarg before
+# any submodule's ``logging.getLogger(__name__)`` call runs. See
+# ``jvagent/_logging_compat.py`` and AUDIT-INDEX §2.2.
+from jvagent._logging_compat import install as _install_logging_compat
+
+_install_logging_compat()
+
+# Register markdown extensions in ``mimetypes`` so jvspatial's storage MIME
+# allow-list accepts ``.md`` saves on hosts without libmagic or an OS mime
+# entry for markdown. Must run before any file-save path. See
+# ``jvagent/_mimetypes_compat.py``.
+from jvagent._mimetypes_compat import install as _install_mimetypes_compat  # noqa: E402
+
+_install_mimetypes_compat()
+
+from jvagent import embed  # noqa: E402  -- must follow logging shim install
+from jvagent.version import __version__  # noqa: E402
+
+__all__ = ["__version__", "embed"]

jvagent/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running jvagent as a module: python -m jvagent"""
+
+from jvagent.cli import main
+
+if __name__ == "__main__":
+    main()

jvagent/_logging_compat.py

@@ -0,0 +1,70 @@
+"""Logger compatibility shim.
+
+jvagent calls ``logger.error(..., details={...})`` extensively across the
+codebase. Stdlib :class:`logging.Logger` does not accept ``details`` as a
+kwarg; it raises ``TypeError: Logger._log() got an unexpected keyword
+argument 'details'``. This shim installs a :class:`Logger` subclass that
+recognizes ``details=`` and routes it to ``extra["details"]`` so that
+:class:`jvspatial.logging.handler.DBLogHandler` picks it up under its
+documented ``extra`` contract.
+
+Install BEFORE any ``logging.getLogger(...)`` call in jvagent — see
+``jvagent/__init__.py``.
+"""
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+
+class JvAgentLogger(logging.Logger):
+    """Stdlib-compatible :class:`Logger` that also accepts a ``details`` kwarg.
+
+    Any ``details=`` passed to ``logger.error/warning/info/debug/critical``
+    (and the underlying ``_log``) is merged into the ``extra`` dict under the
+    ``"details"`` key. Caller-supplied ``extra["details"]`` wins on collision.
+    All other kwargs pass through unchanged.
+    """
+
+    def _log(
+        self,
+        level: int,
+        msg: object,
+        args: Any,
+        exc_info: Any = None,
+        extra: Any = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        details: Any = None,
+    ) -> None:
+        if details is not None:
+            if extra is None:
+                extra = {"details": details}
+            elif isinstance(extra, Mapping):
+                if "details" not in extra:
+                    extra = {**extra, "details": details}
+        super()._log(
+            level,
+            msg,
+            args,
+            exc_info=exc_info,
+            extra=extra,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+        )
+
+
+def install() -> None:
+    """Install :class:`JvAgentLogger` as the default Logger class.
+
+    Idempotent. Must be called before any ``logging.getLogger(__name__)``
+    call inside jvagent — typically from ``jvagent/__init__.py`` at the very
+    top of the module.
+
+    Loggers created BEFORE this call keep their original class. That's fine:
+    jvagent's own modules are imported after ``jvagent/__init__.py`` runs,
+    so their module-level ``logging.getLogger(__name__)`` returns instances
+    of this subclass.
+    """
+    if not issubclass(logging.getLoggerClass(), JvAgentLogger):
+        logging.setLoggerClass(JvAgentLogger)

jvagent/_mimetypes_compat.py

@@ -0,0 +1,53 @@
+"""Deterministic MIME-type registration for text formats jvagent emits.
+
+jvspatial's local storage validator detects a file's MIME type via
+``python-magic`` when available, otherwise it falls back to the stdlib
+``mimetypes`` module (extension-based). When *neither* knows an extension the
+type resolves to ``application/octet-stream``, which is not in jvspatial's
+allow-list — so the save is rejected with::
+
+    File type 'application/octet-stream' is not in allowed types
+
+Markdown is the common casualty: ``mimetypes`` only maps ``.md`` →
+``text/markdown`` when the host OS mime database (e.g. ``/etc/mime.types``)
+happens to include it. On hosts without that entry and without ``libmagic``
+installed, every ``.md`` an agent writes (research reports, notes, …) fails to
+save even though ``text/markdown`` *is* in jvspatial's allow-list.
+
+We close the gap deterministically by registering the markdown extensions in
+the ``mimetypes`` module at import time, before any file-save path runs. Only
+extensions whose target type is already in jvspatial's default allow-list are
+registered here — this changes detection, never the policy.
+
+This mirrors the early ``_logging_compat`` install in :mod:`jvagent` and must
+run before any submodule performs a save.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+
+# (mime_type, extension) pairs. Each ``mime_type`` MUST already be present in
+# jvspatial's ``FileValidator.DEFAULT_ALLOWED_MIME_TYPES`` — we only fix
+# *detection* of well-known text formats, never the allow-list itself.
+_EXTRA_TYPES = (
+    ("text/markdown", ".md"),
+    ("text/markdown", ".markdown"),
+)
+
+_installed = False
+
+
+def install() -> None:
+    """Register markdown extensions in ``mimetypes`` (idempotent)."""
+    global _installed
+    if _installed:
+        return
+    # ``mimetypes.add_type`` lazily inits the module's maps on first use, so an
+    # explicit init is unnecessary; add_type is safe to call repeatedly.
+    for mime_type, ext in _EXTRA_TYPES:
+        mimetypes.add_type(mime_type, ext)
+    _installed = True
+
+
+__all__ = ["install"]

jvagent/action/AGENTS.md

@@ -0,0 +1 @@
+See [CLAUDE.md](CLAUDE.md) — same agent guide, alternate filename for non-Claude AI agents.

jvagent/action/CLAUDE.md

@@ -0,0 +1,145 @@
+# jvagent/action/ — Agent Guide
+
+> Local guide for the action plugin layer. Cross-link: root [`/CLAUDE.md`](../../CLAUDE.md), [`/.planning/reference/action-authoring.md`](../../.planning/reference/action-authoring.md), [`/.planning/reference/actions-catalog.md`](../../.planning/reference/actions-catalog.md).
+
+---
+
+## 1. What this directory owns
+
+The plugin-loadable extension surface of jvagent:
+
+- **`Action` base** ([`base.py:48`](base.py)) — Node subclass with lifecycle hooks, attribute config, endpoint registration, child-cascade delete, tool exposure to the Executive's Skills center.
+- **`InteractAction`** ([`interact/base.py:32`](interact/base.py)) — see `interact/CLAUDE.md`.
+- **Specialized bases**: `BaseModelAction`, `LanguageModelAction`, `BaseWebSearchAction`, `BaseSTTAction`, `BaseTTSAction`, `VectorStore`.
+- **Concrete plugins** organized by topic: language models, response/bus, Orchestrator, memory-related, channel adapters, productivity integrations, tasks. Catalog in [`/.planning/reference/actions-catalog.md`](../../.planning/reference/actions-catalog.md).
+- **Loader/registry** in `loader/`.
+- **Plugin contracts** in `plugin_contracts.py`.
+
+---
+
+## 2. Key files
+
+| File | Purpose |
+|---|---|
+| `base.py:48` | `Action` base class (canonical) |
+| `base.py:272` | `get_tools()` — default discovers `@tool`-decorated methods via `collect_tools` |
+| `jvagent/tooling/tool_decorator.py` | `@tool` decorator + `collect_tools` — preferred way to publish tools |
+| `jvagent/tooling/signature_schema.py` | signature → JSON Schema deriver used by `@tool` |
+| `base.py:180` | `get_capabilities()` — for ReplyAction prompt aggregation |
+| `base.py:225` | `delete(cascade=True)` — walks outgoing edges and cascade-deletes children |
+| `base.py:256-348` | Lifecycle hook contracts (`on_register`, `on_reload`, `post_register`, `on_startup`, `on_enable`, `on_disable`, `on_deregister`, `pulse`, `healthcheck`) |
+| `base.py:354-460` | Endpoint discovery + unregistration (relies on `/actions/{action_id}/` path prefix) |
+| `base.py:462-542` | Module unload safety (skips core + shared modules) |
+| `base.py:710-852` | `get_action()` / `get_action_by_base_class()` / `get_model_action()` — cross-action lookup |
+| `base.py:881-944` | Package metadata accessors (namespace, version, type) |
+| `base.py:946-1100` | File storage helpers (action-scoped paths) |
+| `interact/base.py:32` | `InteractAction` (see `interact/CLAUDE.md`) |
+| `actions.py` | `Actions` manager node |
+| `endpoints.py` | Top-level action HTTP routes (~9 routes) |
+| `loader/` | Action loader, registry, plugin discovery |
+| `plugin_contracts.py` | Plugin protocol definitions |
+| `streaming.py` | Streaming response helpers |
+
+---
+
+## 3. Contracts (don't break)
+
+1. **`Action` subclasses MUST set `archetype` in `info.yaml`** to match the Python class name. The loader uses it.
+2. **Action endpoints MUST live under `/actions/{action_id}/...`** ([`base.py:373`](base.py)). Deregister scans this prefix; non-conforming endpoints leak after `on_deregister`.
+3. **`get_action()` is `O(1)`; `get_action_by_base_class()` is `O(n)`.** Don't use the latter in hot paths.
+4. **Lifecycle hooks MUST not swallow exceptions** ([`base.py:569+`](base.py)). The framework's `enable()`/`disable()`/`reload()` wrappers log errors automatically with the action context — silencing them hides bugs.
+5. **`Action.metadata` is owned by the loader.** Mutations to it are not persisted across restarts. Use `attribute(...)` fields for persistent state.
+6. **Child Nodes attached via outgoing edges are cascade-deleted** when the action is deleted ([`base.py:225`](base.py)). Always connect via `await self.connect(child, direction="out")`.
+7. **`is_singleton` default is `True`** ([`base.py:221`](base.py)). Override `config.singleton: false` in `info.yaml` if multiple instances per agent are allowed.
+8. **Thin harness** — Actions expose capabilities via `get_tools()`; they must not classify user intent, inject prep steering, auto-store extracted values, or inline multi-step workflows. Put judgment in skill SOPs and domain logic in skill extensions. See [`docs/thin-harness.md`](../../docs/thin-harness.md).
+9. **Prefer the `@tool` decorator over hand-built `Tool()`** — decorate an `async def` method with `@tool` ([`jvagent/tooling/tool_decorator.py`](../tooling/tool_decorator.py)) and the base `get_tools()` auto-publishes it. Name = `{action_name}__{method}` (override with `@tool(name=...)`); description = method docstring's first paragraph; JSON Schema = signature (use `Annotated[T, "desc"]` for per-arg docs). Hand-built `Tool()` and `get_tools()` overrides still work; only override when a tool can't be a decorated method (combine with `collect_tools(self)`).
+
+---
+
+## 4. The four-file pattern
+
+Every action package MUST contain:
+
+```
+{namespace}/{action_name}/
+├── __init__.py              # exports class + imports endpoints (for @endpoint registration)
+├── {action_name}.py         # Action subclass
+├── endpoints.py             # @endpoint-decorated routes
+└── info.yaml                # package metadata
+```
+
+Skeleton and full templates: [`/.planning/reference/action-authoring.md`](../../.planning/reference/action-authoring.md).
+
+---
+
+## 5. Cross-action lookup table
+
+| Need | Method | Cost |
+|---|---|---|
+| One specific class | `await self.get_action(MyActionClass)` | O(1) (cached index) |
+| Class by name string | `await self.get_action("MyActionClass")` | O(1) |
+| Any subclass of a base | `await self.get_action_by_base_class(Base)` | O(n) isinstance scan |
+| Any LM provider | `await self.get_model_action(required=True)` | O(1) if `model_action_type` set, else falls back to base scan |
+| The agent | `await self.get_agent()` | Cached |
+| The App | `await self.get_app()` | Cached singleton |
+
+---
+
+## 6. Tests
+
+- `tests/action/{name}/` per-action tests.
+- `tests/action/test_action_loader.py` — plugin loading.
+- `tests/action/test_action_endpoints.py` — endpoint discovery.
+- `tests/action/test_plugin_system.py` — plugin contracts.
+- `tests/test_tool_schema_audit.py` — tool schema sanity.
+
+```bash
+pytest tests/action/ -v
+```
+
+---
+
+## 7. Adding a new Action
+
+The detailed walkthrough lives at [`/.planning/reference/action-authoring.md`](../../.planning/reference/action-authoring.md) and the runbook at [`/.planning/runbooks/add-action.md`](../../.planning/runbooks/add-action.md). Short version:
+
+1. Pick base class (Action / InteractAction / specialized).
+2. Choose namespace (`jvagent/` for core, otherwise `contrib/` or `custom/`).
+3. Create the 4-file directory.
+4. Define `attribute(...)` fields; implement lifecycle hooks + `execute` (if InteractAction). Publish tools by decorating methods with `@tool` (preferred over overriding `get_tools()`).
+5. Wire endpoints under `/actions/{action_id}/...`.
+6. Add tests under `tests/action/{name}/`.
+7. Update [`actions-catalog.md`](../../.planning/reference/actions-catalog.md).
+
+---
+
+## 8. Traps specific to action/
+
+| Trap | Fix |
+|---|---|
+| Missing `from . import endpoints` in `__init__.py` | Add it; otherwise routes don't register |
+| Class name doesn't match `archetype` in info.yaml | Loader silently skips the package |
+| Heavy work in `__init__` | Use lifecycle hooks (`on_register`, `on_enable`) instead |
+| Forgetting `@compound_index` when adding a queried field | Slow queries at scale |
+| Writing to `self.metadata` | Not persisted; use `attribute(...)` |
+| Endpoints not under `/actions/{action_id}/` | Deregister leaks them |
+| Recursive `await self.get_action(MyAction)` calls | OK (cache returns same instance) but expensive isinstance walks aren't |
+
+---
+
+## 9. Subdirectory pointers
+
+| Subdir | Local guide |
+|---|---|
+| `interact/` | [`interact/CLAUDE.md`](interact/CLAUDE.md) |
+| `interview/` | [`interview/CLAUDE.md`](interview/CLAUDE.md) |
+| `orchestrator/` | (see [`/.planning/adr/0012-skill-executive-architecture.md`](../../.planning/adr/0012-skill-executive-architecture.md)) |
+| All other action dirs | Per-package `info.yaml` + class docstring |
+
+---
+
+## 10. Out of scope here
+
+- Walker mechanics: see `interact/CLAUDE.md`.
+- Executive prompt/loop specifics: see [`/docs/ORCHESTRATOR.md`](../../docs/ORCHESTRATOR.md).
+- Memory graph: see `jvagent/memory/CLAUDE.md`.

jvagent/action/README.md

@@ -0,0 +1,34 @@
+# jvagent.action — package index
+
+Action plugins live under `jvagent/action/{name}/`. Each package owns its Action class,
+`info.yaml`, endpoints, and action-local `utils/`.
+
+## Shared modules (import these across action families)
+
+| Module | Purpose |
+|--------|---------|
+| [`utils/`](utils/) | Multi-consumer helpers: typed endpoint loader, Meta HMAC verify, webhook system user, reconcile |
+| [`interact/`](interact/) | InteractAction base, walker, channel-neutral [`webhook_pipeline`](interact/webhook_pipeline.py) |
+| [`oauth/`](oauth/) | OAuth state node, token crypto, audit logging |
+| [`spreadsheet/`](spreadsheet/) | Vendor-neutral A1 range helpers (Sheets + Excel) |
+| [`skill_spec/`](skill_spec/) | Skill contracts, registries, shared task-lock types |
+| [`model/`](model/) | Language model actions and context |
+| [`manifest`](manifest.py), [`parameters`](parameters.py) | App/action configuration |
+
+## Modularization contract
+
+See [`.planning/reference/action-authoring.md` §15](../.planning/reference/action-authoring.md)
+and [action-modularization-audit.md](../.planning/reference/action-modularization-audit.md).
+
+**Rules (summary):**
+
+1. No imports from sibling action packages except through the shared modules above.
+2. Code moves to a shared path only when **2+ unrelated action families** consume it.
+3. No persisted `Node`/`Object` types under `action/utils/`.
+4. One canonical import path — no re-export shims.
+5. Channel webhook finalization uses `interact.webhook_pipeline` (public API).
+
+## Upload ownership
+
+- **`interact/utils/uploads.py`** — upload parsing constants and helpers (canonical).
+- **`orchestrator/uploads.py`** — orchestrator ingestion reflex only; imports from interact.

jvagent/action/__init__.py

@@ -0,0 +1,33 @@
+"""Action system for jvagent.
+
+This module provides the action management system including:
+- Actions: Manager node for action registration and discovery
+- Action: Base action class for all pluggable actions with CRUD endpoints
+- ActionLoader: Dynamic action discovery and loading
+"""
+
+from jvagent.action.actions import Actions
+from jvagent.action.base import Action
+
+
+def __getattr__(name: str):
+    """Lazy-import heavy loader objects or submodules to avoid circular imports."""
+    if name in ("ActionLoader", "ActionMetadata"):
+        from jvagent.action.loader import ActionLoader, ActionMetadata
+
+        return ActionLoader if name == "ActionLoader" else ActionMetadata
+
+    if name == "interact":
+        import importlib
+
+        return importlib.import_module("jvagent.action.interact")
+
+    if name == "endpoints":
+        import importlib
+
+        return importlib.import_module("jvagent.action.endpoints")
+
+    raise AttributeError(name)
+
+
+__all__ = ["Actions", "Action", "ActionLoader", "ActionMetadata"]

jvagent/action/access_control/README.md

@@ -0,0 +1,230 @@
+# Access Control Action
+
+Role-based access control with user_id-based permissions for secure agent operations.
+
+## Overview
+
+The Access Control Action provides user-based permission management and channel/resource permissions for jvagent applications. Identity is keyed by `user_id` only (no sessions or conversations). It supports allow/deny rules for users and user groups, per-action restriction in the InteractWalker, and programmatic + REST APIs for runtime updates. User groups are scoped by action label (e.g. `default`, `PersonaAction`), allowing different group memberships per action with automatic fallback and merge resolution.
+
+## Features
+
+- **User-only identity**: All permissions key off `user_id`
+- **Channel/Resource permissions**: Fine-grained access by channel and action (InteractAction class name)
+- **User groups**: Assign users to groups scoped by action label for permission inheritance; action-specific groups inherit from the `default` scope
+- **Allow/Deny rules**: Deny rules checked first; allow rules grant access
+- **default_deny**: When true, deny when no rule matches; when false, allow
+- **action_aliases**: Map short names to action class names in config
+- **enforce**: When false, all `has_action_access` checks succeed (policy off). Prefer this over disabling the graph node when you want the action to remain discoverable.
+- **allow_anonymous**: When false (default), empty/missing `user_id` is denied whenever policy applies. Set true only if anonymous interact is intentional.
+- **Exceptions**: Actions exempt from permission checks
+- **Programmatic API**: Add/remove users, groups, and permission rules
+- **Admin REST endpoints**: All agent-scoped via `agent_id` (singleton per agent)
+
+## Agent YAML Configuration
+
+Configure directly under `context` (not under `config`). This ensures attributes are
+populated correctly when running on Lambda and other serverless environments.
+
+```yaml
+actions:
+  - action: jvagent/access_control_action
+    context:
+      enabled: true
+      enforce: true
+      allow_anonymous: false
+      description: "Per-user/group access control for interact actions"
+      default_deny: false
+      action_aliases:
+        persona: PersonaAction
+        report: ReportInterviewSkill
+      permissions:
+        default:
+          any:
+            deny: []
+            allow: [{ group: all, enabled: true }]
+          PersonaAction:
+            deny: []
+            allow: [admins]
+        whatsapp:
+          any:
+            deny: []
+            allow: [{ user: "5926431530", enabled: true }]
+      user_groups:
+        default:
+          admins: [user_abc123, user_def456]
+          support_team: [user_ghi789]
+        PersonaAction:
+          reviewers: [user_xyz]
+      exceptions:
+        - ReplyAction
+        - IntroInteractAction
+```
+
+## Permission Structure
+
+```
+channel -> action_label -> allow/deny -> rules
+```
+
+- **Channel**: "default" (web), "whatsapp", etc.
+- **Action label**: InteractAction class name (e.g. "PersonaAction", "ReportInterviewSkill") or "any"
+- **Allow/Deny**: Deny rules checked first; allow rules grant access
+- **Rules**: `{ user: "user_id" }` or `{ group: "group_name" }`; `group: "all"` matches everyone. Groups resolve per action label with `default` fallback.
+
+## Programmatic API
+
+```python
+# User groups (scoped by action_label, defaults to "default")
+await action.add_user_group("support", ["u1", "u2"])                        # default scope
+await action.add_user_group("reviewers", ["u3"], action_label="PersonaAction")  # action-scoped
+await action.add_user_to_group("admins", "user_abc")                        # default scope
+await action.add_users_to_group("admins", ["u1", "u2"])                      # default scope
+await action.add_user_to_group("reviewers", "u3", action_label="PersonaAction")
+await action.remove_user_from_group("admins", "user_abc")                    # default scope
+await action.remove_user_group("support")                                    # default scope
+await action.remove_user_group("reviewers", action_label="PersonaAction")
+groups = action.get_user_groups()                                           # full nested dict
+groups = action.get_user_groups(action_label="PersonaAction")               # merged (action + default)
+
+# Direct user access (allow/deny)
+await action.add_user_to_allow("default", "PersonaAction", "user_xyz")
+await action.add_user_to_deny("default", "DeleteAction", "user_bad")
+await action.remove_user_from_permission("default", "X", "user_id", from_allow=True)
+
+# Group-based rules
+await action.add_group_to_allow("default", "PersonaAction", "admins")
+await action.add_group_to_deny("default", "DeleteAction", "guests")
+await action.remove_group_from_permission("default", "X", "group", from_allow=True)
+
+# Check access
+has_access = await action.has_action_access(
+    user_id="user_abc",
+    action_label="PersonaAction",
+    channel="default",
+)
+
+# Bulk config (includes default_deny, action_aliases, enforce, allow_anonymous)
+config = action.export_config()
+await action.import_config(config, purge=True)
+```
+
+## REST API (Admin Only)
+
+All endpoints require `auth=True` and `roles=["admin"]`. AccessControlAction is a
+singleton per agent, so all endpoints are agent-scoped via `agent_id`.
+
+### Endpoints (`/agents/{agent_id}/access_control/`)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/config?format=json\|yaml` | Export config |
+| PUT | `/config` | Replace permissions |
+| PATCH | `/config` | Merge permissions |
+| POST | `/check` | Check access (user_id, action_label, channel) |
+| POST | `/user_groups` | Create group (body: `{name, user_ids?, action_label?}`) |
+| GET | `/user_groups?action_label=` | List groups (scoped or full nested) |
+| POST | `/user_groups/{group}/users` | Add users to group (body: `{user_ids, action_label?}`) |
+| DELETE | `/user_groups/{group}/users` | Remove users from group (body: `{user_ids, action_label?}`) |
+| DELETE | `/user_groups/{group}` | Remove group (body: `{action_label?}`) |
+| POST | `/permissions` | Add user/group to allow or deny |
+| DELETE | `/permissions` | Remove user/group from allow or deny |
+
+### Config Endpoint (PUT/PATCH)
+
+Resolves AccessControlAction from `agent_id` (no start_node). Request body:
+
+```json
+{
+  "permissions": {
+    "default": {
+      "any": { "deny": [], "allow": [{ "group": "all", "enabled": true }] },
+      "ReportInterviewSkill": { "deny": [{ "group": "all" }], "allow": [] }
+    },
+    "whatsapp": {
+      "any": { "deny": [], "allow": [{ "group": "all", "enabled": true }] },
+      "ReportInterviewSkill": { "deny": [], "allow": [{ "group": "all", "enabled": true }] }
+    }
+  }
+}
+```
+
+- **PUT**: Replaces permissions entirely. Preserves `user_groups` and `exceptions` (and other non-permissions fields on the node). Use `export_config` / `import_config` in code to replace `default_deny`, `action_aliases`, `enforce`, or `allow_anonymous` in one shot.
+- **PATCH**: Merges permissions at channel level.
+
+## User Groups
+
+User groups are organized by **action label scope**, allowing different group memberships per action:
+
+```yaml
+user_groups:
+  default:                    # Fallback scope — used when the action label has no entry
+    admins: [user_abc123, user_def456]
+    support_team: [user_ghi789]
+  PersonaAction:              # Action-specific scope
+    reviewers: [user_xyz]
+  ReportInterviewSkill:
+    analysts: [user_abc123]
+```
+
+### Resolution
+
+When `_matches_rule` evaluates a `{ group: "admins" }` rule for action label `PersonaAction`:
+
+1. Look up `user_groups["PersonaAction"]["admins"]`
+2. Fall back to `user_groups["default"]["admins"]` if missing
+3. **Merge**: action-specific and default groups are merged (action-specific wins on conflicts)
+
+This means a user in `default.admins` is also considered an admin for `PersonaAction` unless `PersonaAction.admins` overrides it. The special group names `"all"` and `"any"` always match without looking up `user_groups`.
+
+### Legacy Flat Format
+
+The original `user_groups` format was flat: `{ admins: [user_abc] }`. This is auto-migrated to `{ default: { admins: [user_abc] } }` by `_migrate_user_groups()` during `import_config`. Both the programmatic API and REST endpoints accept the flat format for backward compatibility.
+
+### Programmatic API (action_label parameter)
+
+All group methods accept an optional `action_label` parameter (default `"default"`):
+
+| Method | action_label behavior |
+|--------|---------------------|
+| `add_user_group(name, user_ids, action_label)` | Creates group under the given scope |
+| `add_user_to_group(group, user_id, action_label)` | Adds user to group in the given scope |
+| `add_users_to_group(group, user_ids, action_label)` | Adds users to group in the given scope |
+| `remove_user_from_group(group, user_id, action_label)` | Removes user from group in the given scope |
+| `remove_user_group(name, action_label)` | Deletes group from the given scope |
+| `get_user_groups(action_label)` | No argument → full nested dict; with label → merged dict for that scope |
+
+### REST API (action_label parameter)
+
+All `user_groups` endpoints accept an `action_label` field in the request body (or query param for GET), defaulting to `"default"`:
+
+| Endpoint | action_label source |
+|----------|-------------------|
+| `POST /user_groups` | Body: `{name, user_ids?, action_label?}` |
+| `GET /user_groups?action_label=` | Query param (omit for full nested structure) |
+| `POST /user_groups/{group}/users` | Body: `{user_ids, action_label?}` |
+| `DELETE /user_groups/{group}/users` | Body: `{user_ids, action_label?}` |
+| `DELETE /user_groups/{group}` | Body: `{action_label?}` |
+
+## Integration
+
+- **Policy applies** when the graph node is `enabled` and `enforce` is true (`policy_applies()`). If there is **no** `AccessControlAction` on the agent, interact proceeds without access checks (open by default).
+- **Session gate**: After `memory.get_session()` resolves `user_id`, the walker checks resource `interact` before creating an interaction. Configure `default` / `whatsapp` / … channel keys for `interact` alongside per–class-name keys.
+- **InteractWalker**: Before each foreground `InteractAction` runs, access is checked using that action’s class name. Deferred (`run_in_background`) actions are checked when queued and again before `execute` in the background runner.
+- **HTTP `/interact`**: Entry access is enforced inside the walker (not on the raw request parameter alone), so `session_id`-only clients are evaluated after session resolution.
+- **WhatsApp webhook**: Uses `sender` (phone) as `user_id` for channel `whatsapp`; denials emit structured logs (`access_control_denied`).
+- **Duplicates**: If more than one `AccessControlAction` exists for an agent, an error is logged and the first match is used—fix the graph to a single node.
+
+## Migration (breaking)
+
+- **`user_groups` is now nested by action label**: The flat format `{ admins: [...] }` is auto-migrated to `{ default: { admins: [...] } }`. Existing YAML configs with flat `user_groups` continue to work via `_migrate_user_groups()`, but new configs should use the nested format.
+- Empty `user_id` no longer bypasses checks when policy applies; set `allow_anonymous: true` only if you need that behavior.
+- Turning off enforcement: set `enforce: false` (or disable the graph node); do not rely on old "empty user always allowed" behavior.
+- Background interact actions are now subject to the same rules as foreground actions.
+- Export/import round-trips `default_deny`, `action_aliases`, `enforce`, and `allow_anonymous`; merge import deduplicates `exceptions` entries.
+- All group-related API methods now accept an `action_label` parameter (default `"default"`). Code calling these methods without the parameter is unaffected.
+
+## Channel Adapters
+
+Channels that receive requests before user resolution (e.g. WhatsApp with `sender` phone) should either:
+- Resolve to `user_id` via `memory.get_session()` before the access check, or
+- Use the channel-specific stable ID (e.g. phone number) as `user_id` in config.

jvagent/action/access_control/__init__.py

@@ -0,0 +1,10 @@
+"""Access Control action package.
+
+This module provides role-based access control for agent operations.
+"""
+
+# Import endpoints to register them
+from . import endpoints  # noqa: F401
+from .access_control_action import AccessControlAction
+
+__all__ = ["AccessControlAction"]