tenaxisos-sdk 0.2.0__tar.gz

tenaxisos_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tenaxisai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tenaxisos_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: tenaxisos-sdk
+Version: 0.2.0
+Summary: Build, validate, sign, and publish TenaxisOS packages and playbooks
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Dynamic: license-file
+
+# tenaxisos-sdk
+
+Python SDK and CLI for building, testing, signing, and publishing TenaxisOS
+packages — agents, MCP servers, and playbooks that install into a TenaxisOS
+kernel and can be shared through the Tenaxis Hub.
+
+## What this is
+
+`tenaxisos-sdk` is the toolkit for building community capabilities for
+TenaxisOS:
+
+- **Author** agents and MCP servers as plain Python, using `Agent` and
+  `MCPServer` base classes with host-brokered LLM/tool/file access — no
+  network calls, secrets, or infrastructure of your own to manage.
+- **Test locally** against `LocalMockHost`, a fake host that lets you drive
+  and assert on agent/tool behavior entirely offline.
+- **Build** a signed, versioned package manifest from your code.
+- **Publish** to the Tenaxis Hub (or import straight into a kernel you
+  control for local development) so others can discover and install it.
+
+## Getting started
+
+The fastest way in is [`examples/`](examples/) — three runnable,
+heavily-commented examples, one per authoring surface (native agent, MCP
+server, LangChain framework adapter). Each has its own tests you can run
+immediately, no kernel or network required:
+
+```bash
+pip install -e ".[dev,mcp,langchain]"
+pytest examples/minimal_text_agent/test_agent.py -v
+```
+
+See [`examples/README.md`](examples/README.md) for which one to start with.
+
+## Documentation
+
+Prose tutorials — go here once you know which capability you're building
+and want more depth than the examples give:
+
+- [Writing a native agent](docs/native_agent_tutorial.md)
+- [Writing an MCP server](docs/mcp_server_tutorial.md)
+- [Local testing with `LocalMockHost`](docs/local_testing.md)
+- [Publishing and installing](docs/publish_and_install.md)
+- [Runtime permission outcomes](docs/runtime_outcomes.md)
+
+## What this contains
+
+| Directory | Purpose |
+|---|---|
+| `src/tenaxisos_sdk/core/` | Manifest validation, JSON Schema loading, Ed25519 signing/verification |
+| `src/tenaxisos_sdk/agents/` | `Agent`/`RunContext`/`Finding` authoring surface, manifest generation |
+| `src/tenaxisos_sdk/host/` | The host-brokered contract (`Host` protocol, `ToolOutcome`) every agent runs against |
+| `src/tenaxisos_sdk/testing/` | `LocalMockHost` — no-kernel local test host |
+| `src/tenaxisos_sdk/tools/` | `Tool`/`MCPServer` authoring surface, MCP manifest generation, `[mcp]` extra for the real stdio protocol bridge |
+| `src/tenaxisos_sdk/cli/` | The `tenaxis` CLI: `validate`, `build`, `sign`, `verify`, `test`, `publish`, `import`, `keygen`, `run`, `agent build`, `mcp init/test/build`, `workflow import` |
+| `src/tenaxisos_sdk/runtime/adapters/` | Agent framework adapters (LangChain today, `[langchain]` optional extra) |
+| `src/tenaxisos_sdk/importers/` | External-workflow importers (n8n today) used by `tenaxis workflow import` |
+
+This package is **not yet published to PyPI** — install it from source
+(below) in the meantime.
+
+## Prerequisites
+
+- **Python 3.11 or 3.12**.
+- No database, no server, no `.env` file — the CLI is stateless and takes
+  everything (hub URL, API keys, key paths) as command-line flags.
+
+## Installation
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate   # optional but recommended
+pip install -e ".[dev]"     # editable install + pytest/ruff; drop [dev] for CLI-only use
+tenaxis --help
+```
+
+Add `[langchain]` (e.g. `pip install -e ".[dev,langchain]"`) if you need the
+LangChain agent adapter, or `[mcp]` if you need to run an MCP server as a
+real stdio process — both are kept optional so the base SDK never requires
+heavy adapter-specific dependencies.
+
+## Everyday usage
+
+```bash
+tenaxis keygen                                        # once — generates an Ed25519 signing key pair
+tenaxis validate <manifest.json>                       # schema + structural validation
+tenaxis test <manifest.json>                           # runs the package's declared tests
+tenaxis build <manifest-dir> --out <out.package.json>  # produces a distributable package artifact
+tenaxis sign <manifest.json> --key <private-key-path>  # signing ceremony (human-reviewed, not run in CI)
+tenaxis verify <manifest.json> --pubkey <public-key-b64> [--require]
+tenaxis publish <manifest.json> --hub <hub-url> --api-key <publisher-api-key>
+tenaxis import <n8n-export.json> --out <package-dir>   # n8n → native workflow package
+```
+
+`tenaxis keygen` writes your private signing key to disk (permissions locked
+to owner-only) — keep it out of version control and treat it like any other
+private key material; the CLI never transmits or stores it for you.
+
+### Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+ruff check src/ tests/
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tenaxisos_sdk-0.2.0/README.md

@@ -0,0 +1,108 @@
+# tenaxisos-sdk
+
+Python SDK and CLI for building, testing, signing, and publishing TenaxisOS
+packages — agents, MCP servers, and playbooks that install into a TenaxisOS
+kernel and can be shared through the Tenaxis Hub.
+
+## What this is
+
+`tenaxisos-sdk` is the toolkit for building community capabilities for
+TenaxisOS:
+
+- **Author** agents and MCP servers as plain Python, using `Agent` and
+  `MCPServer` base classes with host-brokered LLM/tool/file access — no
+  network calls, secrets, or infrastructure of your own to manage.
+- **Test locally** against `LocalMockHost`, a fake host that lets you drive
+  and assert on agent/tool behavior entirely offline.
+- **Build** a signed, versioned package manifest from your code.
+- **Publish** to the Tenaxis Hub (or import straight into a kernel you
+  control for local development) so others can discover and install it.
+
+## Getting started
+
+The fastest way in is [`examples/`](examples/) — three runnable,
+heavily-commented examples, one per authoring surface (native agent, MCP
+server, LangChain framework adapter). Each has its own tests you can run
+immediately, no kernel or network required:
+
+```bash
+pip install -e ".[dev,mcp,langchain]"
+pytest examples/minimal_text_agent/test_agent.py -v
+```
+
+See [`examples/README.md`](examples/README.md) for which one to start with.
+
+## Documentation
+
+Prose tutorials — go here once you know which capability you're building
+and want more depth than the examples give:
+
+- [Writing a native agent](docs/native_agent_tutorial.md)
+- [Writing an MCP server](docs/mcp_server_tutorial.md)
+- [Local testing with `LocalMockHost`](docs/local_testing.md)
+- [Publishing and installing](docs/publish_and_install.md)
+- [Runtime permission outcomes](docs/runtime_outcomes.md)
+
+## What this contains
+
+| Directory | Purpose |
+|---|---|
+| `src/tenaxisos_sdk/core/` | Manifest validation, JSON Schema loading, Ed25519 signing/verification |
+| `src/tenaxisos_sdk/agents/` | `Agent`/`RunContext`/`Finding` authoring surface, manifest generation |
+| `src/tenaxisos_sdk/host/` | The host-brokered contract (`Host` protocol, `ToolOutcome`) every agent runs against |
+| `src/tenaxisos_sdk/testing/` | `LocalMockHost` — no-kernel local test host |
+| `src/tenaxisos_sdk/tools/` | `Tool`/`MCPServer` authoring surface, MCP manifest generation, `[mcp]` extra for the real stdio protocol bridge |
+| `src/tenaxisos_sdk/cli/` | The `tenaxis` CLI: `validate`, `build`, `sign`, `verify`, `test`, `publish`, `import`, `keygen`, `run`, `agent build`, `mcp init/test/build`, `workflow import` |
+| `src/tenaxisos_sdk/runtime/adapters/` | Agent framework adapters (LangChain today, `[langchain]` optional extra) |
+| `src/tenaxisos_sdk/importers/` | External-workflow importers (n8n today) used by `tenaxis workflow import` |
+
+This package is **not yet published to PyPI** — install it from source
+(below) in the meantime.
+
+## Prerequisites
+
+- **Python 3.11 or 3.12**.
+- No database, no server, no `.env` file — the CLI is stateless and takes
+  everything (hub URL, API keys, key paths) as command-line flags.
+
+## Installation
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate   # optional but recommended
+pip install -e ".[dev]"     # editable install + pytest/ruff; drop [dev] for CLI-only use
+tenaxis --help
+```
+
+Add `[langchain]` (e.g. `pip install -e ".[dev,langchain]"`) if you need the
+LangChain agent adapter, or `[mcp]` if you need to run an MCP server as a
+real stdio process — both are kept optional so the base SDK never requires
+heavy adapter-specific dependencies.
+
+## Everyday usage
+
+```bash
+tenaxis keygen                                        # once — generates an Ed25519 signing key pair
+tenaxis validate <manifest.json>                       # schema + structural validation
+tenaxis test <manifest.json>                           # runs the package's declared tests
+tenaxis build <manifest-dir> --out <out.package.json>  # produces a distributable package artifact
+tenaxis sign <manifest.json> --key <private-key-path>  # signing ceremony (human-reviewed, not run in CI)
+tenaxis verify <manifest.json> --pubkey <public-key-b64> [--require]
+tenaxis publish <manifest.json> --hub <hub-url> --api-key <publisher-api-key>
+tenaxis import <n8n-export.json> --out <package-dir>   # n8n → native workflow package
+```
+
+`tenaxis keygen` writes your private signing key to disk (permissions locked
+to owner-only) — keep it out of version control and treat it like any other
+private key material; the CLI never transmits or stores it for you.
+
+### Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+ruff check src/ tests/
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tenaxisos_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tenaxisos-sdk"
+version = "0.2.0"
+description = "Build, validate, sign, and publish TenaxisOS packages and playbooks"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "jsonschema>=4.23",
+    "cryptography>=42",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+tenaxis = "tenaxisos_sdk.cli.main:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.4",
+]
+# LangChain agent adapter — kept optional so the base SDK
+# (build/sign/validate/publish) never requires heavy adapter-specific
+# dependencies.
+langchain = [
+    "langchain-core>=0.3",
+]
+# MCP server authoring. Only needed to actually run
+# `tenaxisos_sdk.tools.stdio.run_stdio`; declaring/testing tools via
+# `tenaxisos_sdk.tools.MCPServer` needs no extra.
+mcp = [
+    "mcp>=1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"tenaxisos_sdk.core" = ["schemas/*.json"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

tenaxisos_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tenaxisos_sdk-0.2.0/src/tenaxisos_sdk/__init__.py

@@ -0,0 +1,14 @@
+"""TenaxisOS SDK — build, validate, sign, and publish packages."""
+
+__version__ = "0.2.0"
+
+# The SDK authoring/runtime host contract version (`compatibility.sdk_api` in
+# a package manifest). Distinct axis from `__version__`: this only changes
+# when the *shape* of `tenaxisos_sdk.agents`/`tenaxisos_sdk.host` changes in
+# a way that could break a package built against an older contract (a new
+# required `Host` method, a renamed `Agent` method, a changed `ToolOutcome`
+# member) — not on every release. Bump both together only when a release
+# happens to also be a contract change. The kernel checks a package's
+# declared `compatibility.sdk_api` range against this value before running
+# packages that rely on the public SDK runtime contract.
+SDK_API_VERSION = "0.2.0"

tenaxisos_sdk-0.2.0/src/tenaxisos_sdk/agents/__init__.py

@@ -0,0 +1,20 @@
+from tenaxisos_sdk.agents.base import Agent, ProgressCallback
+from tenaxisos_sdk.agents.context import RunContext
+from tenaxisos_sdk.agents.findings import (
+    BASE_INPUT_SCHEMA,
+    FINDING_SCHEMA,
+    Finding,
+    validate_findings,
+)
+from tenaxisos_sdk.agents.manifest import generate_agent_payload
+
+__all__ = [
+    "Agent",
+    "ProgressCallback",
+    "RunContext",
+    "Finding",
+    "FINDING_SCHEMA",
+    "BASE_INPUT_SCHEMA",
+    "validate_findings",
+    "generate_agent_payload",
+]

tenaxisos_sdk-0.2.0/src/tenaxisos_sdk/agents/base.py

@@ -0,0 +1,277 @@
+"""Agent — the SDK's public agent-authoring base class.
+
+Provides the shape a native agent needs (metadata class attributes,
+`add_finding`/`set_output`/`effective_config`/`progress`/`fail`, an
+abstract `run()`) while keeping every LLM/tool/file call routed through a
+`Host` (`tenaxisos_sdk.host`) supplied at construction time, never through
+a direct kernel import. In production the kernel supplies a `Host`
+implementation that binds this same class to real governance; for local
+development, `tenaxisos_sdk.testing.local_host.LocalMockHost` is a
+deterministic fake, so an author can write and run tests with no kernel
+installed.
+
+What this deliberately does NOT include, since these are the kernel's job,
+not something an agent author should reach for directly:
+- No org/tenant injection, no direct tool registry access — the host
+  decides how a tool call actually executes.
+- No LLM provider/task-hint routing — the host's `llm_complete` already
+  returns a routed, governed completion.
+- No integration wire-name resolution — an agent calls `self.tools.call(name,
+  args)` by logical name; the host resolves the underlying wiring.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Awaitable, Callable, Optional
+
+from tenaxisos_sdk.agents.context import RunContext
+from tenaxisos_sdk.agents.findings import BASE_INPUT_SCHEMA, Finding
+from tenaxisos_sdk.host import Host, ToolCallResult
+
+ProgressCallback = Callable[[int, str], Awaitable[None]]
+
+
+class Agent(ABC):
+    """Base class for all SDK-authored agents.
+
+    Each agent implements `run()` and returns a list of `Finding` dicts via
+    `self.findings` / `self.add_finding(...)`.
+    """
+
+    # -- Metadata (override in subclass) ----------------------------------
+    display_name: str = "Unknown Agent"
+    description: str = ""
+    category: str = "general"
+    tools: list[str] = []
+    capability_tags: list[str] = []
+    toolchains: list[str] = []
+    input_types: list[str] = []
+    output_types: list[str] = []
+    CONFIG_SCHEMA: dict = {}
+    INPUT_SCHEMA: dict = {}
+    OUTPUT_SCHEMA: dict = {}
+    DECLARED_OUTPUT_SHAPE: dict = {}
+    privacy_tier: str = "standard"
+    # -- Behaviour contract ------------------------------------------------
+    version: str = "1.0.0"
+    deterministic: bool = True
+    idempotent: bool = True
+    side_effects: str = "none"  # none | external | irreversible
+    _skip_schema_validation: bool = False
+
+    def __init__(self, config: dict | None = None, *, host: Host) -> None:
+        """`host` is required and keyword-only: an `Agent` never has an
+        implicit default authority channel. Callers must be explicit about
+        whether they're binding to `LocalMockHost` or a production host."""
+        self.config: dict[str, Any] = config or {}
+        self._host = host
+        self.findings: list[Finding] = []
+        self.output: dict[str, Any] = {}
+        self.log_lines: list[str] = []
+        self._run_failed = False
+        self._fail_reason = ""
+        self.ctx = RunContext(self.config.get("context", {}))
+        self._validate_config_schema()
+
+    # -- Contract validation -------------------------------------------------
+
+    def workflow_variables(self) -> dict[str, Any]:
+        """Flat workflow/run variable values resolved for this run."""
+        workflow = self.config.get("workflow", {})
+        if isinstance(workflow, dict):
+            variables = workflow.get("effective_variables", {})
+            if isinstance(variables, dict):
+                return variables
+        return {}
+
+    def workflow_var(self, name: str, default: Any = None) -> Any:
+        """Read a resolved workflow variable by name."""
+        return self.workflow_variables().get(name, default)
+
+    def effective_config(self, name: str | None = None, default: Any = None) -> Any:
+        """Read the node's effective runtime config.
+
+        Effective config is derived by the host using this priority:
+        agent defaults < workflow variables < run variables < node config.
+        """
+        effective = self.config.get("effective_config")
+        if not isinstance(effective, dict):
+            effective = self.config
+        if name is None:
+            return effective
+        return effective.get(name, default)
+
+    def _validate_config_schema(self) -> None:
+        if self.__class__._skip_schema_validation:
+            return
+        schema = self.__class__.CONFIG_SCHEMA or {}
+        missing = [k for k, v in schema.items() if v.get("required") and k not in self.config]
+        if missing:
+            raise ValueError(
+                f"{self.__class__.__name__}: missing required config fields: {', '.join(missing)}"
+            )
+
+    def validate_input(self, runtime_data: dict) -> list[str]:
+        """Validate runtime execution data against INPUT_SCHEMA. Returns a
+        list of error strings — empty means valid."""
+        errors: list[str] = []
+        schema = {**BASE_INPUT_SCHEMA, **self.__class__.INPUT_SCHEMA}
+        for field_name, spec in schema.items():
+            if spec.get("required") and field_name not in runtime_data:
+                errors.append(f"missing required input field: '{field_name}'")
+            if field_name in runtime_data:
+                allowed = spec.get("enum")
+                val = runtime_data[field_name]
+                if allowed is not None and val not in allowed:
+                    errors.append(
+                        f"input field '{field_name}' must be one of {allowed}, got {val!r}"
+                    )
+        return errors
+
+    def validate_output(self, findings: list) -> list[str]:
+        """Validate findings against `FINDING_SCHEMA` before they're stored.
+        Returns a list of warning strings — empty means valid. Non-fatal:
+        callers should append error findings rather than aborting the run."""
+        from tenaxisos_sdk.agents.findings import validate_findings
+
+        return validate_findings(findings)
+
+    # -- Host-brokered channels ----------------------------------------------
+
+    async def call_tool(
+        self, name: str, args: Optional[dict[str, Any]] = None, **kwargs: Any
+    ) -> ToolCallResult:
+        """Propose a tool call through the host. The host decides
+        allow/deny/approval/dry-run — this never executes anything itself."""
+        payload: dict[str, Any] = dict(args or {})
+        payload.update(kwargs)
+        result = await self._host.call_tool(name, payload)
+        self.log_lines.append(f"[tool] {name}: {result.outcome.value}")
+        return result
+
+    async def llm_complete(
+        self, prompt: str, system: str | None = None, category: str = "llm"
+    ) -> str | None:
+        """Complete a prompt through the host's governed LLM channel.
+
+        Mirrors `BaseAgent.llm_complete`: emits an 'error' severity finding
+        on failure instead of raising, and returns None so callers can check
+        the result without a try/except.
+        """
+        try:
+            return await self._host.llm_complete(prompt, system)
+        except Exception as exc:  # noqa: BLE001 - host failures are reported as findings, not raised
+            self.add_finding(
+                severity="error",
+                category=category,
+                title="LLM call failed",
+                message=str(exc),
+            )
+            return None
+
+    async def read_file(self, path: str) -> str:
+        return await self._host.read_file(path)
+
+    async def read_file_bytes(self, path: str) -> bytes:
+        return await self._host.read_file_bytes(path)
+
+    async def list_files(self, path: str, pattern: str = "*") -> list[str]:
+        return await self._host.list_files(path, pattern)
+
+    # -- Run lifecycle --------------------------------------------------------
+
+    @abstractmethod
+    async def run(self, on_progress: ProgressCallback | None = None) -> list[dict]:
+        """Execute the agent. Should call `self.progress(...)` periodically.
+        Returns findings as dicts (use `self.findings_as_dicts()`)."""
+
+    async def progress(self, on_progress: Optional[ProgressCallback], pct: int, msg: str) -> None:
+        self.log_lines.append(f"[{pct}%] {msg}")
+        if on_progress:
+            await on_progress(pct, msg)
+
+    def fail(self, reason: str) -> None:
+        """Mark this run as failed without raising — the caller records
+        status='error' even though `run()` returned normally."""
+        self._run_failed = True
+        self._fail_reason = reason
+
+    @property
+    def failed(self) -> bool:
+        return self._run_failed
+
+    @property
+    def fail_reason(self) -> str:
+        return self._fail_reason
+
+    # -- Findings / outputs ----------------------------------------------------
+
+    def add_finding(
+        self,
+        severity: str,
+        category: str,
+        title: str,
+        message: str,
+        file: str | None = None,
+        line: int | None = None,
+        rule: str | None = None,
+        suggestion: str | None = None,
+        **extra: Any,
+    ) -> Finding:
+        f = Finding(severity, category, title, message, file, line, rule, suggestion)
+        f.extra.update({k: v for k, v in extra.items() if v is not None})
+        self.findings.append(f)
+        return f
+
+    def findings_as_dicts(self) -> list[dict]:
+        return [f.to_dict() for f in self.findings]
+
+    def set_output(self, name: str, value: Any) -> None:
+        """Record a declared contract output for this run. The key must be
+        declared in `output_types`."""
+        if name == "findings" or name not in self.__class__.output_types:
+            raise ValueError(
+                f"{self.__class__.__name__}: output '{name}' is not declared in output_types"
+            )
+        self.output[name] = value
+
+    def output_as_dict(self) -> dict[str, Any]:
+        return dict(self.output)
+
+    def summary(self) -> dict:
+        counts: dict[str, int] = {}
+        for f in self.findings:
+            counts[f.severity] = counts.get(f.severity, 0) + 1
+        return {"total": len(self.findings), "by_severity": counts}
+
+    @classmethod
+    def docs_metadata(cls) -> dict:
+        """Structured documentation metadata. See `agents/manifest.py` for
+        full package-manifest generation."""
+        config_docs = {}
+        for k, v in (cls.CONFIG_SCHEMA or {}).items():
+            config_docs[k] = {
+                "type": v.get("type", "str"),
+                "required": v.get("required", False),
+                "description": v.get("desc", v.get("description", "")),
+                "default": v.get("default"),
+            }
+        return {
+            "name": cls.display_name,
+            "category": cls.category,
+            "description": cls.description,
+            "input_types": list(cls.input_types),
+            "output_types": list(cls.output_types),
+            "config": config_docs,
+            "tools": list(cls.tools),
+            "capability_tags": list(cls.capability_tags),
+            "toolchains": list(cls.toolchains),
+            "privacy_tier": cls.privacy_tier,
+            "version": cls.version,
+            "deterministic": cls.deterministic,
+            "idempotent": cls.idempotent,
+            "side_effects": cls.side_effects,
+            "input_schema": dict(cls.INPUT_SCHEMA),
+            "output_schema": dict(cls.OUTPUT_SCHEMA),
+            "declared_output_shape": dict(cls.DECLARED_OUTPUT_SHAPE),
+        }