Walkthrough

This PR introduces the foundational TypeScript contracts and registry for the messaging manifest system. It adds JSON-serializable type definitions for channel manifests with auth, credentials, and render specs, an in-memory registry with duplicate detection and filtering, comprehensive tests validating the type system and module isolation, and index files wiring the exports.

Changes

Messaging Manifest Type System and Registry

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• #3996: Related work on built-in messaging manifest registration and parity tests for built-in channel manifests.

Suggested labels

OpenShell

Suggested reviewers

• ericksoa

Poem

🐰 A manifest fair, in types defined,
A registry keen with filters aligned,
No secrets bare in the plans we hold—
Just placeholders wise and isolation bold! ✨

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. No required E2E because the changed production files add an isolated, side-effect-free messaging manifest/registry module that is not imported by current onboarding, sandbox lifecycle, credential provider, policy, inference, or channel command paths. Unit tests in the PR cover the new contracts; optional messaging E2Es are listed only for adjacent confidence.

Optional E2E

• messaging-providers-e2e (high): Optional adjacent confidence for the existing messaging credential provider/placeholder/L7-proxy chain. The PR only introduces currently isolated manifest contracts, so this is not merge-blocking unless the manifest module becomes wired into onboarding or channel application.
• channels-add-remove-e2e (high): Optional adjacent confidence for user-facing channel add/remove policy and rebuild behavior, which is the likely future consumer of manifest policyPresets, credentials, and render declarations. Not required because the new module is not currently used by that path.

New E2E recommendations

• messaging manifest runtime integration (high): There is no existing E2E that exercises a ChannelManifest through compilation/application into OpenShell providers, policy presets, agent config rendering, persisted state, rebuild hydration, and hook handling. Existing E2Es cover the legacy channel paths rather than this new manifest abstraction.
  • Suggested test: Add a hermetic manifest-driven channel E2E that registers Telegram and WeChat-style manifests, compiles a SandboxMessagingPlan, applies it to an OpenClaw sandbox with fake credentials, verifies only OpenShell placeholders appear in agent config, confirms policy presets are applied, and checks raw secret values do not leak to env/process/files.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: ``

PR Review Advisor

Base: origin/main
Head: HEAD
Analyzed SHA: e0ca92f34b3189e4bedc15d2c8a477e9b392710f
Recommendation: blocked
Confidence: high

The code change is isolated and well-covered by unit tests, but the PR is currently blocked by GitHub mergeability/review gates and should not be treated as merge-ready yet.

Gate status

• CI: pass — Required contexts checks, commit-lint, dco-check, check-hash, and changes completed successfully for e0ca92f; non-required build-sandbox-images contexts were still in progress.
• Mergeability: fail — GitHub reports mergeStateStatus=BLOCKED and reviewDecision=REVIEW_REQUIRED for head e0ca92f.
• Review threads: pass — GraphQL reviewThreads.nodes is empty and there are no review comments in the provided trusted context.
• Risky code tested: pass — Path heuristics found no active sandbox lifecycle, credential provider, policy enforcement, Dockerfile, installer, workflow, or network boundary changes; E2E Advisor also classified the new manifest/registry module as isolated.

🔴 Blockers

• GitHub mergeability gate is blocked: The latest trusted PR metadata reports mergeStateStatus=BLOCKED with reviewDecision=REVIEW_REQUIRED, so the PR is not currently mergeable even though required status checks are passing.
  • Recommendation: Resolve the repository review/mergeability requirements and re-check the gate state for the same head SHA before considering merge.
  • Evidence: headSha=e0ca92f34b3189e4bedc15d2c8a477e9b392710f; GraphQL mergeStateStatus=BLOCKED; reviewDecision=REVIEW_REQUIRED.

🟡 Warnings

• Manifest trust boundary is type-only and not enforced at runtime (src/lib/messaging/manifest/registry.ts:17): The registry accepts ChannelManifest objects and stores them directly. The current PR is intentionally isolated, but the new manifest shape includes future security-sensitive declarations such as policyPresets, render targets, credential placeholders, hooks, build args, and build files. If future work loads manifests from user-controlled or extension-controlled sources without runtime validation, this could become a blueprint-tampering or policy-bypass path.
  • Recommendation: Before wiring this registry into onboarding, channel application, rebuild, rendering, or credential flows, add a runtime schema/validator with allowlists for IDs, env names, render targets, hook handler names, policy presets, and build-file paths; document that repository-owned manifests are trusted code, and consider cloning/freezing registered manifests.
  • Evidence: ChannelManifestRegistry.register(manifest: ChannelManifest) only checks duplicate IDs before storing the object; types.ts defines policyPresets, render, hooks, and SandboxMessagingBuildInputPlan fields that will be security-sensitive once consumed.

🔵 Suggestions

• None.

Acceptance coverage

• met — Add src/lib/messaging/manifest/types.ts.: New file src/lib/messaging/manifest/types.ts added with manifest and plan contracts.
• met — Define ChannelManifest with channel identity, supported agents, auth, inputs, credentials, policy, render, state, and hook specs.: types.ts defines ChannelManifest with schemaVersion, id, displayName, supportedAgents, auth, inputs, credentials, policyPresets, render, state, and hooks.
• partial — Define initial serializable plan shapes for future compilation, including channel plans, credential bindings, policy requirements, render fragments, build inputs, state updates, and hook references.: types.ts defines SandboxMessagingPlan, SandboxMessagingChannelPlan, credentialBindings, policyPresets, render fragments, buildInputs, and hooks. Explicit state update plan entries are limited to input statePath/rebuildHydration-related structures rather than a separate state update plan type.
• met — Model secrets as references/placeholders only. Do not store raw secret values in the plan.: SandboxMessagingCredentialBindingPlan contains placeholder/provider fields and no value field; types.test.ts asserts serialized plans contain openshell placeholders and not a raw token, and credentialBindings do not have value.
• met — Add index exports for the new module surface.: src/lib/messaging/index.ts exports ./manifest; src/lib/messaging/manifest/index.ts exports registry and type exports from types.
• met — Manifest and plan objects can be JSON-serialized and parsed back without losing required fields.: types.test.ts includes jsonRoundTrip coverage for representative ChannelManifest fixtures and SandboxMessagingPlan fixtures and checks required fields after parse.
• met — Manifest types contain no function-valued fields.: types.test.ts includes compile-time FunctionFieldKey assertions for ChannelManifest and SandboxMessagingPlan plus runtime recursive checks on fixtures; hooks use string handler references.
• met — The new module does not import gateway, registry, credentials, filesystem, subprocess, OpenShell adapter, or command/action layers.: Production files under src/lib/messaging only import local type/registry modules; types.test.ts scans production import/export specifiers for forbidden fragments including gateway, state/registry, credentials, node:fs, child_process, adapters/openshell, src/commands, and lib/actions.
• met — Tests include representative fixture manifests and prove secret values are not required in fixtures.: types.test.ts defines Telegram and WeChat-style fixtures, verifies JSON round trips, and asserts no raw secret token is serialized or required.
• met — Existing onboarding, channel add/remove, rebuild, OpenClaw rendering, and Hermes rendering behavior is unchanged.: The diff only adds new src/lib/messaging files and exports; no existing onboarding, channel lifecycle, rebuild, OpenClaw rendering, or Hermes rendering files are modified. E2E Advisor also reports the module is not imported by current production workflow paths.
• met — Current channel metadata starts in src/lib/sandbox/channels.ts, but phase 1 should introduce the next contracts beside it rather than replacing it.: No changes to src/lib/sandbox/channels.ts are present; the new contracts are added beside existing code under src/lib/messaging.
• met — Add src/lib/messaging/manifest/registry.ts.: New file src/lib/messaging/manifest/registry.ts added.
• met — Support register(manifest), get(channelId), list(), and listAvailable(ctx).: ChannelManifestRegistry implements register, get, list, and listAvailable; registry.test.ts exercises each method.
• met — Keep the registry in-memory and side-effect free.: registry.ts uses an internal Map and has no filesystem, subprocess, network, credential, gateway, or adapter imports.
• met — Preserve current platform support semantics when filtering available manifests by agent.: listAvailable filters by supportedAgents when agent is provided and registry.test.ts verifies agent-based filtering.
• met — Duplicate channel IDs are rejected.: register throws Duplicate channel manifest id '' when the id already exists; registry.test.ts asserts duplicate Telegram manifests throw.
• met — Registered manifests can be retrieved by channel ID.: registry.test.ts registers TELEGRAM_MANIFEST and expects registry.get('telegram') to return the same manifest.
• met — list() returns registered manifests in registration order.: registry.ts returns Array.from(this.manifests.values()), preserving Map insertion order; registry.test.ts checks list output for registered manifests.
• met — listAvailable(ctx) filters by manifest-supported agent.: registry.test.ts verifies listAvailable({ agent: 'hermes' }) returns only the Telegram manifest when WeChat supports only openclaw.
• met — listAvailable(ctx) treats an empty or omitted platform support list as no platform filter, matching current behavior.: registry.ts converts empty supportedChannelIds to null filter; registry.test.ts verifies omitted and empty supportedChannelIds both include Telegram and WeChat.

Security review

• pass — 1. Secrets and Credentials: No hardcoded real secrets or credential files were added. The plan model uses placeholders/references, and tests explicitly assert raw secret values are not serialized and credential bindings do not contain a value property.
• warning — 2. Input Validation and Data Sanitization: Current changes are type contracts and an in-memory registry, but there is no runtime validation for manifest IDs, env keys, render targets, hook handlers, policy presets, or build file paths. This is acceptable while isolated, but must be addressed before manifests are loaded from any untrusted source or applied to sandbox/render/rebuild flows.
• pass — 3. Authentication and Authorization: No endpoints, authentication checks, authorization logic, token validation, or permission boundaries are modified. Auth modes are declarative manifest metadata only.
• pass — 4. Dependencies and Third-Party Libraries: No new dependencies, package manifests, lockfiles, registries, or third-party library versions are changed.
• pass — 5. Error Handling and Logging: The only new thrown error is duplicate manifest ID detection. No logging of secrets, PII, stack traces, or internal state is introduced.
• pass — 6. Cryptography and Data Protection: Not applicable — no cryptographic operations, encryption, hashing, signing, or data protection primitives are introduced.
• pass — 7. Configuration and Security Headers: No HTTP endpoints, CORS/CSP headers, Dockerfiles, containers, ports, debug settings, or runtime security configuration are changed. Policy preset and render fields are declarative and currently unused by production flows.
• pass — 8. Security Testing: Unit tests cover JSON serializability, absence of function-valued fields in fixtures, placeholder-only secret handling, duplicate ID rejection, filtering semantics, and isolation from forbidden side-effect layers. E2E Advisor found no required E2E for this isolated phase.
• warning — 9. Holistic Security Posture: The current isolated change does not degrade active production behavior, but the new manifest abstraction will become security-sensitive once connected to policy, credential, hook, render, rebuild, or sandbox lifecycle code. Future integration should enforce a trusted-code boundary, runtime schema validation, and anti-tampering controls.

Test / E2E status

• Test depth: unit_sufficient — The production change adds isolated TypeScript contracts and a side-effect-free in-memory registry that is not wired into current onboarding, channel lifecycle, credential, policy, sandbox, or rendering paths. The added unit tests cover the new behavior and security-relevant invariants for this phase; E2E Advisor found no required E2E for the current head SHA.
• E2E Advisor: ok

✅ What looks good

• The PR is additive and does not modify existing onboarding, channel lifecycle, rebuild, rendering, credential, policy, sandbox, workflow, or installer paths.
• The registry implementation is small, deterministic, in-memory, and has duplicate-ID and filtering tests.
• Secret handling is modeled as placeholders/references and is backed by tests that check raw secret values are not serialized.
• The module isolation test helps prevent accidental imports from filesystem, subprocess, gateway, credential, adapter, command, and action layers.

Review completeness

• This advisory review used the provided trusted metadata and diff; no tests or package-manager commands were executed.
• PR title/body/comments and linked issue text were treated as untrusted evidence and cross-checked against the diff where possible.
• The PR remains subject to repository mergeability and human review requirements; this advisor does not approve or merge changes.
• Human maintainer review required: yes