decepticon-core 1.1.2__tar.gz

decepticon_core-1.1.2/.gitignore

@@ -0,0 +1,117 @@
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# IDE and Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Python specific
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Node
+node_modules/
+
+# etc
+sliver-py/
+/src/
+config/*.local.*
+reference/
+demo.tape
+
+# Decepticon runtime data
+.decepticon/
+.dogfood/
+workspace/
+.bg-shell/
+
+.langgraph_api/
+.omc/
+.ouroboros/
+.gstack/
+.claude/
+clients/ee/
+
+# Project-specific Claude Code instructions (private)
+CLAUDE.md
+references/octogent
+clients/launcher/decepticon
+
+# Benchmark
+# Per-run artefacts (timestamped batch + evidence/ + reports/) are local-only.
+# Curated per-challenge results (XBEN-*-24/) and the LEVEL3 index are committed.
+# LangSmith trace dumps live as public share URLs in READMEs — never committed.
+benchmark/results/*
+!benchmark/results/.gitkeep
+!benchmark/results/XBEN-*-24/
+!benchmark/results/README.md
+benchmark/results/XBEN-*-24/evidence/langsmith_trace.json
+benchmark/results/XBEN-*-24/evidence/iter14_pass.json
+benchmark/results/XBEN-*-24/evidence/*_iter*.json
+# Per-run timestamped subdirs inside XBEN-*-24/ are local dev artefacts.
+# The flat root (report.json / report.md / evidence/summary.{json,md}) is the
+# committed PASS record — see benchmark/results/README.md for the policy.
+benchmark/results/XBEN-*-24/2[0-9][0-9][0-9][0-9][0-9][0-9][0-9]_*/
+benchmark/workspaces/
+
+# Codex / OMX runtime artefacts (never committed)
+.omx/
+.env.bak.*
+benchmark/results/XBEN-*-24/run-loop*.log
+
+# Git worktrees
+.worktrees/

decepticon_core-1.1.2/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: decepticon-core
+Version: 1.1.2
+Summary: Decepticon contract layer: pure types, protocols, plugin contracts, registry primitives
+Project-URL: Homepage, https://github.com/PurpleAILAB/Decepticon
+Project-URL: Repository, https://github.com/PurpleAILAB/Decepticon
+Author: Decepticon Team
+License: Apache-2.0
+Keywords: agents,ai,contracts,plugins,red-team,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Description-Content-Type: text/markdown
+
+# decepticon-core
+
+The Decepticon contract layer. Pure types, protocols, plugin contracts,
+and registry primitives — zero `langchain` / `langgraph` / `deepagents`
+runtime dependency. Suitable to import from any context: CLI tooling,
+serverless workers, type-checking-only environments.
+
+Stable surface for plugin authors and downstream commercial layers
+(e.g. SaaS dashboards, B2B API services). See the umbrella
+[`README.md`](../../README.md) and the design spec at
+[`docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md`](../../docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md).
+
+## Install
+
+```bash
+pip install decepticon-core
+```
+
+Most consumers should install `decepticon` (which depends on this) or
+`decepticon-sdk` (the plugin-author entrypoint).

decepticon_core-1.1.2/README.md

@@ -0,0 +1,20 @@
+# decepticon-core
+
+The Decepticon contract layer. Pure types, protocols, plugin contracts,
+and registry primitives — zero `langchain` / `langgraph` / `deepagents`
+runtime dependency. Suitable to import from any context: CLI tooling,
+serverless workers, type-checking-only environments.
+
+Stable surface for plugin authors and downstream commercial layers
+(e.g. SaaS dashboards, B2B API services). See the umbrella
+[`README.md`](../../README.md) and the design spec at
+[`docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md`](../../docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md).
+
+## Install
+
+```bash
+pip install decepticon-core
+```
+
+Most consumers should install `decepticon` (which depends on this) or
+`decepticon-sdk` (the plugin-author entrypoint).

decepticon_core-1.1.2/decepticon_core/__init__.py

@@ -0,0 +1,43 @@
+"""decepticon-core — contract layer for the Decepticon agent framework.
+
+Pure types, protocols, plugin contracts, and registry primitives. This
+package never imports ``langchain``, ``langgraph``, ``deepagents``,
+``httpx``, or ``fastapi`` — see the design spec at
+``docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md``.
+
+Phase 1.A status: ``types`` submodule extracted from the framework
+(engagement / llm / kg). Subsequent commits add ``protocols``,
+``contracts``, ``registry``, and ``utils`` per spec §6.1.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from decepticon_core import (
+    contracts,
+    plugin_loader,
+    protocols,
+    registry,
+    types,
+    utils,
+)
+
+try:
+    # pyproject carries a "0.0.0" sentinel; release.yml stamps the real
+    # tag into the wheel metadata at build time, and importlib.metadata
+    # reads it back here. Local checkouts read 0.0.0.
+    __version__ = _version("decepticon-core")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "contracts",
+    "plugin_loader",
+    "protocols",
+    "registry",
+    "types",
+    "utils",
+]

decepticon_core-1.1.2/decepticon_core/contracts/__init__.py

@@ -0,0 +1,35 @@
+"""Plugin contracts — the surface plugin authors implement against.
+
+Submodules:
+
+  * ``slots`` — middleware slot enum and per-role applicability mapping.
+    Was ``decepticon.agents.middleware_slots``; framework keeps the
+    default factory helpers (which need langchain runtime) and imports
+    the enum/constants from here.
+
+Future Phase 1 commits will add ``contributions`` (ToolContribution,
+MiddlewareContribution, PromptContribution, SubAgentContribution,
+SafetyDeclaration) and ``PluginBundle`` proper (currently lives at
+``decepticon_core.plugin_loader`` after Phase 1.B).
+"""
+
+from __future__ import annotations
+
+from decepticon_core.contracts import contributions, slots
+from decepticon_core.contracts.contributions import (
+    MiddlewareContribution,
+    PromptContribution,
+    SafetyDeclaration,
+    SubAgentContribution,
+    ToolContribution,
+)
+
+__all__ = [
+    "MiddlewareContribution",
+    "PromptContribution",
+    "SafetyDeclaration",
+    "SubAgentContribution",
+    "ToolContribution",
+    "contributions",
+    "slots",
+]

decepticon_core-1.1.2/decepticon_core/contracts/contributions.py

@@ -0,0 +1,153 @@
+"""Focused contribution dataclasses for plugin authors.
+
+Per spec §7.2 Principle 3, the kitchen-sink ``PluginBundle`` of the
+pre-redesign era splits into five focused contribution types — each
+covers one extension surface so plugin authors construct just what
+they need and the framework's introspection (``PluginRegistry``)
+attributes overrides to specific contributions.
+
+The aggregate ``PluginBundle`` (currently at
+``decepticon_core.plugin_loader``) keeps a back-compat shape during
+the transition; Phase 2 introduces the rebuilt version that aggregates
+these contributions.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class ToolContribution:
+    """Tools a plugin contributes to one or more roles.
+
+    Mirrors the old ``PluginBundle.replaced_tools`` / ``disabled_tools``
+    fields, but typed precisely and with the ``roles`` field
+    intentionally required (no implicit "all roles" — closes gap §8
+    #6). An empty ``roles`` tuple raises ``ValueError`` at construction.
+
+    Fields:
+        items: tools added to the role's tool list.
+        disabled_names: tool names to remove from the OSS baseline.
+        replaced: name -> replacement tool (combines disable + add).
+        roles: roles this contribution applies to. ``()`` is rejected
+            at construction time.
+    """
+
+    items: tuple[Any, ...] = ()
+    disabled_names: tuple[str, ...] = ()
+    replaced: Mapping[str, Any] = field(default_factory=dict)
+    roles: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.roles:
+            raise ValueError(
+                "ToolContribution requires an explicit non-empty ``roles=`` tuple "
+                "(closes spec §8 gap #6 — implicit all-roles is forbidden). "
+                "Pass roles=('recon',) etc."
+            )
+
+
+@dataclass(frozen=True)
+class MiddlewareContribution:
+    """Middleware a plugin contributes to one or more roles.
+
+    Same shape as ``ToolContribution`` but keyed by slot name (the
+    ``MiddlewareSlot`` value). ``roles`` is required at construction.
+    """
+
+    items: tuple[Any, ...] = ()
+    disabled_slots: tuple[str, ...] = ()
+    replaced_slots: Mapping[str, Any] = field(default_factory=dict)
+    roles: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.roles:
+            raise ValueError(
+                "MiddlewareContribution requires an explicit non-empty "
+                "``roles=`` tuple (closes spec §8 gap #6). Pass roles=('recon',) etc."
+            )
+
+
+@dataclass(frozen=True)
+class PromptContribution:
+    """Prompt fragments a plugin contributes to one or more roles.
+
+    Closes gap §8 #8 (prompt-only plugin no longer has to wrap in
+    ``PluginBundle``) — packages can ship a ``PromptContribution``
+    directly under the new ``decepticon.prompts`` entry-point group.
+
+    Fields:
+        fragments: role name -> text. The framework applies the
+            fragment per the ``mode`` setting.
+        mode: ``prepend`` / ``append`` / ``replace`` (replace wholly
+            substitutes the loaded prompt; prepend/append wrap it).
+        roles: roles this contribution applies to.
+    """
+
+    fragments: Mapping[str, str] = field(default_factory=dict)
+    mode: Literal["prepend", "append", "replace"] = "append"
+    roles: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.roles:
+            raise ValueError(
+                "PromptContribution requires an explicit non-empty ``roles=`` "
+                "tuple (closes spec §8 gap #6). Pass roles=('recon',) etc."
+            )
+
+
+@dataclass(frozen=True)
+class SubAgentContribution:
+    """Sub-agents a plugin contributes to one or more parent agents.
+
+    Mirrors the parent-agent scoping used by ``load_subagents_for_parent``
+    in ``decepticon_core.plugin_loader``. The ``items`` carry
+    ``SubAgentSpec`` objects (defined in plugin_loader, eventually to
+    move under ``contracts``). ``parent_agents`` required.
+    """
+
+    items: tuple[Any, ...] = ()
+    disabled_names: tuple[str, ...] = ()
+    replaced: Mapping[str, Any] = field(default_factory=dict)
+    parent_agents: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.parent_agents:
+            raise ValueError(
+                "SubAgentContribution requires an explicit non-empty "
+                "``parent_agents=`` tuple (closes spec §8 gap #6). "
+                "Pass parent_agents=('decepticon',) etc."
+            )
+
+
+@dataclass(frozen=True)
+class SafetyDeclaration:
+    """Plugin-declared additions to the safety-critical set.
+
+    Per spec §16.4 #4 this contract is **additive only**: plugins can
+    declare *their own* tool / middleware names safety-critical, but
+    cannot remove safety on OSS-declared names. The framework merges
+    plugin SafetyDeclarations with ``SAFETY_CRITICAL_TOOLS`` /
+    ``SAFETY_CRITICAL_SLOTS`` from ``decepticon-core``.
+
+    Fields:
+        tools: tool names the plugin marks safety-critical.
+        middleware: middleware slot names the plugin marks
+            safety-critical. Custom plugin slot names are accepted
+            (any string).
+    """
+
+    tools: tuple[str, ...] = ()
+    middleware: tuple[str, ...] = ()
+
+
+__all__ = [
+    "MiddlewareContribution",
+    "PromptContribution",
+    "SafetyDeclaration",
+    "SubAgentContribution",
+    "ToolContribution",
+]

decepticon_core-1.1.2/decepticon_core/contracts/slots.py

@@ -0,0 +1,135 @@
+"""Middleware slot enum and per-role applicability mapping.
+
+The Decepticon agent factories assemble their middleware stack by
+walking ``MiddlewareSlot`` in declaration order; each role declares
+which slots apply via ``SLOTS_PER_ROLE``.
+
+This module is the pure-data half of the original
+``decepticon.agents.middleware_slots``. The langchain/deepagents-bound
+default factories (``DEFAULT_SLOT_FACTORIES`` and the ``_make_*``
+helpers) stay in the framework — keeping core langchain-free.
+
+Plugin authors implementing custom middleware reach for
+``MiddlewareSlot`` and the ``SAFETY_CRITICAL_SLOTS`` set when wiring
+``PluginBundle.replaced_middleware`` / ``disabled_middleware``.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class MiddlewareSlot(StrEnum):
+    """Named slots in the agent middleware stack.
+
+    Enum declaration order = assembly order. The 16 agent factories
+    walk this enum top-to-bottom; only slots in ``SLOTS_PER_ROLE[role]``
+    are instantiated.
+    """
+
+    ENGAGEMENT_CONTEXT = "engagement-context"
+    SKILLS = "skills"
+    FILESYSTEM = "filesystem"
+    SUBAGENT = "subagent"
+    OPPLAN = "opplan"
+    SANDBOX_NOTIFICATION = "sandbox-notification"
+    MODEL_OVERRIDE = "model-override"
+    MODEL_FALLBACK = "model-fallback"
+    SUMMARIZATION = "summarization"
+    PROMPT_CACHING = "prompt-caching"
+    PATCH_TOOL_CALLS = "patch-tool-calls"
+
+
+SAFETY_CRITICAL_SLOTS: frozenset[MiddlewareSlot] = frozenset(
+    {
+        # EngagementContextMiddleware carries RoE constraints into every
+        # tool call — disabling it lets an agent target out-of-scope
+        # hosts without any guard rail. Replacement is fine if the new
+        # middleware honours the same contract; full disable is the
+        # actual hazard.
+        MiddlewareSlot.ENGAGEMENT_CONTEXT,
+        # SandboxNotification tracks background-job completion + emits
+        # the CLI's ``● Background command`` event. Disabling it leaves
+        # operator visibility broken on every background tool call.
+        MiddlewareSlot.SANDBOX_NOTIFICATION,
+    }
+)
+"""Slots a plugin can only replace/disable when
+``DECEPTICON_ALLOW_SAFETY_OVERRIDES=1`` is set in the environment.
+
+The gate is enforced by ``build_middleware`` in
+``decepticon.agents.build``. Plugins are expected to honour the
+overall contract (e.g. a replacement EngagementContextMiddleware still
+needs to inject scope) — the gate exists so an accidentally-installed
+plugin can't silently subvert the safety story.
+"""
+
+
+# Common slots every agent uses (the "tail" of the middleware stack).
+_TAIL_SLOTS: frozenset[MiddlewareSlot] = frozenset(
+    {
+        MiddlewareSlot.MODEL_FALLBACK,
+        MiddlewareSlot.SUMMARIZATION,
+        MiddlewareSlot.PROMPT_CACHING,
+        MiddlewareSlot.PATCH_TOOL_CALLS,
+    }
+)
+
+# Base slots — knowledge + filesystem + tail. Every agent gets these.
+_BASE_SLOTS: frozenset[MiddlewareSlot] = _TAIL_SLOTS | {
+    MiddlewareSlot.SKILLS,
+    MiddlewareSlot.FILESYSTEM,
+}
+
+# Standard bash-executing agents (recon/exploit/postexploit/analyst/
+# reverser/contract_auditor/cloud_hunter/ad_operator + plugin
+# specialists verifier/patcher/scanner/exploiter): base + engagement
+# context + sandbox notification.
+_BASH_AGENT_SLOTS: frozenset[MiddlewareSlot] = _BASE_SLOTS | {
+    MiddlewareSlot.ENGAGEMENT_CONTEXT,
+    MiddlewareSlot.SANDBOX_NOTIFICATION,
+}
+
+
+SLOTS_PER_ROLE: dict[str, frozenset[MiddlewareSlot]] = {
+    # ── Standard orchestrator ──
+    "decepticon": _BASE_SLOTS
+    | {
+        MiddlewareSlot.ENGAGEMENT_CONTEXT,
+        MiddlewareSlot.SUBAGENT,
+        MiddlewareSlot.OPPLAN,
+        MiddlewareSlot.MODEL_OVERRIDE,
+    },
+    # ── Standard non-bash agent (planning + interview) ──
+    "soundwave": _BASE_SLOTS | {MiddlewareSlot.ENGAGEMENT_CONTEXT},
+    # ── Standard bash-executing specialists ──
+    "recon": _BASH_AGENT_SLOTS,
+    "exploit": _BASH_AGENT_SLOTS,
+    "postexploit": _BASH_AGENT_SLOTS,
+    "analyst": _BASH_AGENT_SLOTS,
+    "reverser": _BASH_AGENT_SLOTS,
+    "contract_auditor": _BASH_AGENT_SLOTS,
+    "cloud_hunter": _BASH_AGENT_SLOTS,
+    "ad_operator": _BASH_AGENT_SLOTS,
+    # ── Plugin orchestrator (no EngagementContext per the existing
+    # vulnresearch factory — it consumes its parent's context) ──
+    "vulnresearch": _BASE_SLOTS | {MiddlewareSlot.SUBAGENT, MiddlewareSlot.OPPLAN},
+    # ── Plugin read-only specialist (no bash, no SandboxNotification) ──
+    "detector": _BASE_SLOTS,
+    # ── Plugin bash-executing specialists ──
+    "verifier": _BASH_AGENT_SLOTS,
+    "patcher": _BASH_AGENT_SLOTS,
+    "scanner": _BASH_AGENT_SLOTS,
+    "exploiter": _BASH_AGENT_SLOTS,
+}
+"""Role → slot-set mapping. The assembler only walks slots present in
+the role's set; anything else is skipped silently. Plugin agents
+register their own role here via the ``decepticon.agents`` entry-point
+group (handled by ``plugin_loader``)."""
+
+
+__all__ = [
+    "MiddlewareSlot",
+    "SAFETY_CRITICAL_SLOTS",
+    "SLOTS_PER_ROLE",
+]