pynydus.engine.packager

Egg packaging and reading: archive operations for .egg files.

An .egg file is a zip archive with the canonical directory layout::

manifest.json
signature.json           (optional: Ed25519 signature over modules)
spawn_log.json           (structured spawn pipeline log)
nydus.json               (per-skill ID/agent_type mapping)
mcp.json                 (MCP server configs, Claude Desktop format)
agent-card.json          (A2A agent card, optional)
apm.yml                  (passthrough from source, optional)
AGENTS.md                (per-egg deployment runbook, optional)
skills/<slug>/SKILL.md   (Agent Skills format: agentskills.io)
specs/...                (embedded spec snapshots, optional)
memory.json
secrets.json
raw/...
Nydusfile                (spawn DSL)

Module Contents

Functions

_sign_if_key	Return signature data dict if a private key is provided.
_write_skills_to_zip	Write each skill as skills/<slug>/SKILL.md.
_write_mcp_to_zip	Write MCP configs as a single mcp.json in Claude Desktop format.
_read_skills_from_zip	Read skills from skills/<slug>/SKILL.md + nydus.json.
_read_mcp_from_zip	Read MCP configs from mcp.json (Claude Desktop format).
_write_egg_archive	Write an Egg to a .egg archive (zip-based).
save	Write an Egg to a .egg file, including raw/ and spawn_log.json.
_unpack_egg_core	Load manifest, skills, MCP, memory, and secrets from an archive.
read_spawn_log_list	Return the spawn pipeline log as a list (same as spawn_log.json body).
load	Load a fully populated :class:~pynydus.api.schemas.Egg from a .egg archive.
read_raw_artifacts	Read raw/ artifacts from an Egg archive.
read_logs	Read structured logs from an Egg archive.
read_nydusfile	Read the embedded Nydusfile text from an Egg archive, or None if absent.
read_signature	Read signature.json from an Egg archive, or None if unsigned.
_read_skills_bytes_for_verification	Reconstruct the skills bytes used for signing.
verify_egg_archive	Verify an egg archive’s signature.

Data

logger
MANIFEST_ENTRY
MEMORY_ENTRY
SECRETS_ENTRY
SIGNATURE_ENTRY
NYDUS_META_ENTRY
SPAWN_LOG_ENTRY
MCP_ENTRY
AGENT_CARD_ENTRY
APM_ENTRY
AGENTS_MD_ENTRY
EMBEDDED_NYDUSFILE_NAME
SKILLS_PREFIX
SPECS_PREFIX
RAW_PREFIX
_LEGACY_MCP_PREFIX

API

pynydus.engine.packager.logger

‘getLogger(…)’

pynydus.engine.packager.MANIFEST_ENTRY

‘manifest.json’

pynydus.engine.packager.MEMORY_ENTRY

‘memory.json’

pynydus.engine.packager.SECRETS_ENTRY

‘secrets.json’

pynydus.engine.packager.SIGNATURE_ENTRY

‘signature.json’

pynydus.engine.packager.NYDUS_META_ENTRY

‘nydus.json’

pynydus.engine.packager.SPAWN_LOG_ENTRY

‘spawn_log.json’

pynydus.engine.packager.MCP_ENTRY

‘mcp.json’

pynydus.engine.packager.AGENT_CARD_ENTRY

‘agent-card.json’

pynydus.engine.packager.APM_ENTRY

‘apm.yml’

pynydus.engine.packager.AGENTS_MD_ENTRY

‘AGENTS.md’

pynydus.engine.packager.EMBEDDED_NYDUSFILE_NAME

‘Nydusfile’

pynydus.engine.packager.SKILLS_PREFIX

‘skills/’

pynydus.engine.packager.SPECS_PREFIX

‘specs/’

pynydus.engine.packager.RAW_PREFIX

‘raw/’

pynydus.engine.packager._LEGACY_MCP_PREFIX

‘mcp/’

pynydus.engine.packager._sign_if_key(private_key: cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey | None, content_parts: list[bytes]) → dict | None

Return signature data dict if a private key is provided.

pynydus.engine.packager._write_skills_to_zip(zf: zipfile.ZipFile, skills: pynydus.api.schemas.SkillsModule) → bytes

Write each skill as skills/<slug>/SKILL.md.

Also writes nydus.json (per-skill tracking metadata sidecar).

Returns the concatenated bytes of all SKILL.md files (sorted by slug) for deterministic signing.

pynydus.engine.packager._write_mcp_to_zip(zf: zipfile.ZipFile, mcp: pynydus.api.schemas.McpModule) → None

Write MCP configs as a single mcp.json in Claude Desktop format.

pynydus.engine.packager._read_skills_from_zip(zf: zipfile.ZipFile) → pynydus.api.schemas.SkillsModule

Read skills from skills/<slug>/SKILL.md + nydus.json.

pynydus.engine.packager._read_mcp_from_zip(zf: zipfile.ZipFile) → pynydus.api.schemas.McpModule

Read MCP configs from mcp.json (Claude Desktop format).

Falls back to legacy mcp/<name>.json per-server files for old eggs.

pynydus.engine.packager._write_egg_archive(egg: pynydus.api.schemas.Egg, output_path: pathlib.Path, raw_artifacts: dict[str, str] | None = None, spawn_log: list[dict] | None = None, *, nydusfile_text: str | None = None, private_key: cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey | None = None) → pathlib.Path

Write an Egg to a .egg archive (zip-based).

pynydus.engine.packager.save(egg: pynydus.api.schemas.Egg, output_path: pathlib.Path, *, raw_artifacts: dict[str, str] | None = None, spawn_log: list[dict] | None = None, nydusfile_text: str | None = None, private_key: cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey | None = None) → pathlib.Path

Write an Egg to a .egg file, including raw/ and spawn_log.json.

Uses egg.raw_artifacts, egg.spawn_log, and egg.nydusfile when the corresponding keyword arguments are omitted.

Args: egg: Egg to serialize. output_path: Destination path (.egg suffix applied if missing). raw_artifacts: Redacted raw/ snapshot. defaults to egg.raw_artifacts. spawn_log: Pipeline log. defaults to egg.spawn_log. nydusfile_text: Embedded DSL text. defaults to egg.nydusfile. private_key: If set, signs manifest + module payloads (Ed25519).

Returns: Path to the written .egg archive.

pynydus.engine.packager._unpack_egg_core(egg_path: pathlib.Path) → pynydus.api.schemas.Egg

Load manifest, skills, MCP, memory, and secrets from an archive.

pynydus.engine.packager.read_spawn_log_list(egg_path: pathlib.Path) → list[dict]

Return the spawn pipeline log as a list (same as spawn_log.json body).

Args: egg_path: Path to the .egg archive.

Returns: Log entries, or an empty list if the entry is missing or not a list.

pynydus.engine.packager.load(egg_path: pathlib.Path, *, include_raw: bool = True) → pynydus.api.schemas.Egg

Load a fully populated :class:~pynydus.api.schemas.Egg from a .egg archive.

Includes spawn_log.json as spawn_log and embedded Nydusfile text when present. When include_raw is True (default), raw/ entries are read into raw_artifacts. Set include_raw=False to skip loading raw/ (empty dict) and reduce memory use for large archives. use :func:read_raw_artifacts when you need raw/ for passthrough hatch or inspection.

Args: egg_path: Path to the .egg archive. include_raw: When False, skip reading raw/ into memory.

Returns: Egg with modules, optional raw_artifacts, spawn_log, and nydusfile.

pynydus.engine.packager.read_raw_artifacts(egg_path: pathlib.Path) → dict[str, str]

Read raw/ artifacts from an Egg archive.

Args: egg_path: Path to the .egg archive.

Returns: Mapping of relative path (under raw/) to UTF-8 text content.

pynydus.engine.packager.read_logs(egg_path: pathlib.Path) → dict[str, list]

Read structured logs from an Egg archive.

Args: egg_path: Path to the .egg archive.

Returns: Dict keyed by ZIP entry name (e.g. spawn_log.json) to parsed JSON lists.

pynydus.engine.packager.read_nydusfile(egg_path: pathlib.Path) → str | None

Read the embedded Nydusfile text from an Egg archive, or None if absent.

Args: egg_path: Path to the .egg archive.

Returns: Embedded Nydusfile source, or None if not stored in the archive.

pynydus.engine.packager.read_signature(egg_path: pathlib.Path) → dict | None

Read signature.json from an Egg archive, or None if unsigned.

Args: egg_path: Path to the .egg archive.

Returns: Parsed signature payload, or None when the archive is unsigned.

pynydus.engine.packager._read_skills_bytes_for_verification(zf: zipfile.ZipFile) → bytes

Reconstruct the skills bytes used for signing.

pynydus.engine.packager.verify_egg_archive(egg_path: pathlib.Path) → bool | None

Verify an egg archive’s signature.

Args: egg_path: Path to the .egg archive.

Returns: True if a signature is present and valid. False if present but invalid (tampered). None if the egg is unsigned.