feat(messaging): add manifest types and registry

[sandl99]

Summary

Adds the phase-1 messaging manifest foundation under src/lib/messaging: serializable manifest/plan type contracts plus a small in-memory manifest registry. This phase is intentionally isolated: no existing onboarding, channel lifecycle, rendering, policy, credential, or rebuild production workflow imports or consumes these contracts yet.

Related Issue

Fixes #3991
Fixes #3992
Part of #3896

Changes

• Add the src/lib/messaging module surface.
• Define serializable channel manifest contracts for identity, auth, inputs, credentials, policy presets, rendering, state, and hook declarations.
• Define a simple nested SandboxMessagingPlan shape for future compiler/applier work without wiring it into production code.
• Add an in-memory ChannelManifestRegistry with register, get, list, and listAvailable.
• Keep registry behavior side-effect free and preserve current agent/platform filtering semantics.
• Add fixture-based tests for JSON round-trip behavior, hook-handler references instead of functions, no raw secret requirement, side-effect import isolation, duplicate channel IDs, and registry filtering.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npm test -- src/lib/messaging/manifest
• npm run typecheck:cli
• npm run lint
• Pre-push hooks passed after pushing this branch, including TypeScript (CLI) and Test (CLI).

The commit hook's full CLI coverage run hit an existing timeout in test/cli.test.ts (doctor fails a present sandbox that is not Ready); that exact test passed in isolation afterward.

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: San Dang sdang@nvidia.com

Summary by CodeRabbit

• Tests

  • Added comprehensive validation tests for messaging manifests and compiled plans covering serialization, type invariants, secret handling, and registry behavior.

• New Features

  • Added rich, JSON-serializable type definitions for messaging channel manifests, inputs, auth, renders, hooks, and sandbox plans.
  • Added a channel manifest registry with registration, retrieval, listing, and availability filtering.

• Chores

  • Exposed manifest exports through the messaging package and added SPDX license headers.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds serializable TypeScript contracts for messaging channel manifests and sandbox plans, a ChannelManifest registry with availability filtering, barrel exports to expose the manifest surface, and Vitest suites validating JSON round-trips, secret placeholders, absence of function-valued fields, and import-dependency isolation.

Changes

Messaging Manifest Type Contracts

Layer / File(s)	Summary
Type contracts foundation src/lib/messaging/manifest/types.ts	Defines JSON-serializable primitives and messaging identifiers; ChannelManifest (auth, inputs, credentials, render specs, state, hooks) and SandboxMessagingPlan with per-channel plans, input references, credential binding plans (env placeholders), render fragment plans, and build/hook plans.
Module exports and wiring src/lib/messaging/manifest/index.ts, src/lib/messaging/index.ts	Adds SPDX header and barrel re-exports in manifest/index.ts (registry and type-only re-exports from types); updates messaging package entry to export * from "./manifest", exposing manifest types and values.
Registry and registry tests src/lib/messaging/manifest/registry.ts, src/lib/messaging/manifest/registry.test.ts	Implements ChannelManifestRegistry with Map-backed storage, duplicate-ID rejection on register, get, list, listAvailable(ctx?) filtering by agent and supportedChannelIds, and a createChannelManifestRegistry factory; tests cover registration, duplicate detection, and availability filtering.
Test fixtures and validation src/lib/messaging/manifest/types.test.ts	Adds type-level helpers and runtime utilities, representative Telegram and WeChat ChannelManifest fixtures and a Telegram SandboxMessagingPlan; tests assert JSON round-trip fidelity, plans omit raw secret values (use openshell env placeholders), manifests/plans contain no function-valued fields, and production source files do not import forbidden internal or Node APIs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• #3996 — Adds and surfaces messaging manifest types/registries and parity tests; closely related to the manifest/registry exports and tests in this PR.

Suggested labels

enhancement

Suggested reviewers

• ericksoa

Poem

I hop through types and tests today,
Manifest shapes in tidy array,
No secret spills, no functions hide,
Placeholders guard what must reside.
JSON round-trips—now off I play! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(messaging): add manifest types and registry' accurately and concisely summarizes the main changes: introducing manifest type definitions and a registry component to the messaging module.
Linked Issues check	✅ Passed	All PR objectives align with linked issues #3991 and #3992: manifest types are defined with serializable contracts, the registry is implemented with required methods (register, get, list, listAvailable), secrets are modeled as references, JSON serialization works without functions, and module isolation is maintained.
Out of Scope Changes check	✅ Passed	All changes directly support the objectives of issues #3991 and #3992; no out-of-scope modifications detected. Changes include manifest type definitions, registry implementation, comprehensive tests, and proper re-exports through module entry points.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch u/sdang/messaging-manifest-types-3991

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: messaging-providers-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required E2E

• None. No required E2E for this PR: the production changes add a new isolated TypeScript manifest contract/registry module and barrel exports, with nearby unit/contract tests. The diff does not modify the installer, onboarding flow, sandbox lifecycle, credential application code, network policy assets, inference routing, deployment, or existing assistant runtime paths, and repository inspection shows the new module is not yet imported by those runtime flows.

Optional E2E

• messaging-providers-e2e (high): Optional adjacent confidence only: validates the existing token-backed messaging credential provider/placeholder/L7-proxy chain and messaging policy/config paths for current channels. The PR introduces manifest types for the same conceptual surface, but does not yet wire them into runtime onboarding.

New E2E recommendations

• messaging manifest planner/applier integration (medium): Existing E2E jobs exercise legacy hard-coded messaging onboarding flows, but there is no E2E coverage for compiling ChannelManifest declarations into SandboxMessagingPlan objects and applying them to sandbox creation/rebuild once this new manifest system is integrated.
  • Suggested test: Add a manifest-driven messaging E2E that registers a fake token channel manifest, compiles it into a plan, onboards/rebuilds a sandbox, verifies OpenShell provider placeholders are attached, confirms policy presets are applied, and asserts no raw secret appears in host state or rendered agent config.
• host-QR/hook-backed messaging channels (medium): The new contract supports host-qr/in-sandbox-qr auth and declarative hook references with secret/config outputs, but current E2E coverage is focused on existing Telegram/Discord/Slack token flows and Slack pairing. A future WeChat-style hook-backed flow would need end-to-end validation when implemented.
  • Suggested test: Add a hook-backed channel E2E using a hermetic fake QR/hook handler that emits one secret and one config output, then verifies skip-channel/abort behavior, persisted state hydration, provider binding, and rendered agent configuration.

[github-actions]

PR Review Advisor

Recommendation: blocked
Confidence: high
Analyzed HEAD: 5b8e98e9a66a8c65f2d9ad9b92875cbe6019b98f
Findings: 1 blocker(s), 2 warning(s), 1 suggestion(s)

This is an automated advisory review. A human maintainer must make the final merge decision.

Limitations: This advisory review used read-only repository inspection plus trusted deterministic context; it did not execute tests, package-manager commands, workflows, or PR-provided scripts.; CI/status checks are still pending, so required check success for the exact head SHA cannot be fully verified.; The current E2E Advisor check is in progress; an existing E2E Advisor comment recommends no required E2E jobs but does not include an explicit analyzed SHA.; The parent issue #3896 was referenced but its body/comments were not included, so parent acceptance mapping is limited.

Workflow run

Full advisor summary

PR Review Advisor

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

The isolated messaging manifest/registry implementation looks well-scoped and unit-tested, but merge is blocked by GitHub mergeStateStatus=BLOCKED and pending status contexts for the exact head SHA.

Gate status

• CI: pending — Trusted context reports 6 pending status context(s) for head SHA 5b8e98e, including E2E recommendation, PR review advisor, CodeQL jobs, checks, and CodeRabbit.
• Mergeability: fail — GitHub GraphQL mergeStateStatus=BLOCKED and REST mergeable_state=blocked for PR feat(messaging): add manifest types and registry #4000.
• Review threads: pass — Trusted GraphQL context reports 1 review thread and it is resolved.
• Risky code tested: pass — Trusted path heuristics detected no risky code areas; changed files are isolated to src/lib/messaging manifest contracts, registry, tests, and barrel exports.

🔴 Blockers

• GitHub merge state is blocked: The PR is not merge-ready while GitHub reports mergeStateStatus=BLOCKED. This can reflect required reviews, branch protection, pending checks, or other repository gates.
  • Recommendation: Wait until branch protection, required reviews, and required checks are satisfied for head SHA 5b8e98e before merging.
  • Evidence: Trusted context: graphQl.repository.pullRequest.mergeStateStatus=BLOCKED; REST mergeable_state=blocked.

🟡 Warnings

• CI is still pending for the current head SHA: Several status contexts are still in progress or pending, so successful validation for the exact head SHA cannot be confirmed yet.
  • Recommendation: Confirm all required checks complete successfully for 5b8e98e before considering the PR merge-ready.
  • Evidence: Trusted gateStatus.ci says 6 status context(s) appear pending; GraphQL statusCheckRollup includes IN_PROGRESS checks for E2E recommendation, PR review advisor, CodeQL javascript-typescript, CodeQL python, checks, and PENDING CodeRabbit.
• E2E Advisor freshness is ambiguous while its check is in progress: An E2E Advisor comment recommends no required E2E jobs for this isolated manifest/registry phase, but the status rollup shows the current E2E recommendation check is still IN_PROGRESS for the head SHA. The older comment does not include an explicit analyzed SHA.
  • Recommendation: Wait for the E2E recommendation check to complete for 5b8e98e. If it still says Required E2E: None, no additional E2E jobs are required for this phase.
  • Evidence: E2E Advisor comment: Required E2E: None; GraphQL statusCheckRollup: CheckRun name=E2E recommendation status=IN_PROGRESS.

🔵 Suggestions

• Document exact channel ID matching before downstream callers rely on it (src/lib/messaging/manifest/registry.test.ts:35): The registry currently treats channel IDs exactly: get('TELEGRAM') is expected to be undefined and duplicate rejection is exact. This appears intentional after the 'keep registry channel ids exact' commit and resolved CodeRabbit thread, but it is a public contract that future callers may depend on.
  • Recommendation: When manifests become user-facing, document the canonical channel ID expectation. If tolerant lookup is later desired, add normalization consistently across register/get/listAvailable and corresponding tests.
  • Evidence: registry.ts stores manifests by manifest.id and get(channelId) performs direct Map lookup; registry.test.ts asserts registry.get('TELEGRAM') is undefined.

Acceptance coverage

• unknown — Part of Refactor messaging integrations into a manifest-first planning architecture #3896 phase 1.: The PR and linked issues reference parent issue Refactor messaging integrations into a manifest-first planning architecture #3896, but the parent issue body/comments were not included in the trusted context, so parent-level acceptance cannot be mapped.
• met — Add the foundational TypeScript contracts for the isolated src/lib/messaging module. This issue should define the serializable manifest and plan shapes only; it should not switch any current workflow to the new path.: The diff adds new files under src/lib/messaging and does not modify onboarding, channel lifecycle, rendering, policy, credential, rebuild, sandbox lifecycle, or workflow files.
• met — Add src/lib/messaging/manifest/types.ts.: src/lib/messaging/manifest/types.ts is added with 248 lines of manifest and plan contracts.
• met — Define ChannelManifest with channel identity, supported agents, auth, inputs, credentials, policy, render, state, and hook specs.: ChannelManifest in types.ts includes id/displayName/description, supportedAgents, auth, inputs, credentials, optional 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.: SandboxMessagingPlan and SandboxMessagingChannelPlan include channel plans, credentialBindings, policyPresets, render fragments, buildInputs, and hooks. State appears represented via input statePath and manifest rebuildHydration, but there is no distinct first-class state update plan field in SandboxMessagingChannelPlan.
• met — Model secrets as references/placeholders only. Do not store raw secret values in the plan.: Credential specs and binding plans use sourceInput/providerEnvKey/placeholder fields; types.test.ts verifies serialized plan output contains an OpenShell placeholder, does not contain a raw token fixture, and has no value property.
• met — Add index exports for the new module surface.: src/lib/messaging/index.ts exports './manifest'; src/lib/messaging/manifest/index.ts exports registry values and type-only exports from './types'.
• met — Manifest and plan objects can be JSON-serialized and parsed back without losing required fields.: types.test.ts uses jsonRoundTrip on representative Telegram/WeChat manifests and a Telegram SandboxMessagingPlan, then asserts required fields remain present.
• met — Manifest types contain no function-valued fields.: types.test.ts includes compile-time FunctionFieldKey assertions and runtime findFunctionPaths checks for representative manifests/plans.
• met — The new module does not import gateway, registry, credentials, filesystem, subprocess, OpenShell adapter, or command/action layers.: Production files import only local manifest/types/registry modules. The import-isolation test scans production TS files and forbids gateway, state/registry, credentials, node:fs, child_process, adapters/openshell, src/commands, and lib/actions imports.
• met — Tests include representative fixture manifests and prove secret values are not required in fixtures.: types.test.ts includes Telegram and WeChat manifest fixtures plus a Telegram plan; tests verify the raw token fixture is not serialized and credential bindings do not contain a value property.
• partial — Existing onboarding, channel add/remove, rebuild, OpenClaw rendering, and Hermes rendering behavior is unchanged.: The diff only adds isolated src/lib/messaging files and tests, but CI is still pending for the current head SHA, so regression validation is not complete.
• 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.: The diff adds src/lib/messaging/manifest/* and does not modify src/lib/sandbox/channels.ts.
• met — Add the in-memory manifest registry for messaging. This should make typed channel manifests discoverable for later compiler/planner work while keeping phase 1 isolated from current production workflows.: src/lib/messaging/manifest/registry.ts adds ChannelManifestRegistry and createChannelManifestRegistry; no existing production workflow files are modified.
• met — Add src/lib/messaging/manifest/registry.ts.: src/lib/messaging/manifest/registry.ts is added with the registry implementation.
• met — Support register(manifest), get(channelId), list(), and listAvailable(ctx).: ChannelManifestRegistry implements register, get, list, and listAvailable; registry.test.ts covers registration, retrieval, listing, duplicate rejection, and filtering.
• met — Keep the registry in-memory and side-effect free.: registry.ts uses a private Map and imports only types from './types'; it has no filesystem, subprocess, network, credential, adapter, or workflow imports.
• met — Preserve current platform support semantics when filtering available manifests by agent.: listAvailable filters by manifest.supportedAgents when ctx.agent is provided, and tests cover agent filtering and empty supportedChannelIds semantics.
• met — Duplicate channel IDs are rejected.: register throws Duplicate channel manifest id when this.manifests already has manifest.id; registry.test.ts verifies duplicate TELEGRAM_MANIFEST registration throws.
• met — Registered manifests can be retrieved by channel ID.: registry.get(channelId) returns the Map entry keyed by channelId; registry.test.ts verifies get('telegram') returns the registered manifest.

Security review

• pass — 1. Secrets and Credentials: No hardcoded real secrets, PEM files, .env files, credential JSON, or tokens are added. The new contracts model secrets as references/placeholders, and tests assert a raw token fixture is not serialized into the plan.
• warning — 2. Input Validation and Data Sanitization: This PR adds types and an in-memory registry only, with no runtime parsing, command execution, URL fetching, SSRF surface, or file writes. However, future compiler/applier code will consume free-form ids, envKey, handler, statePath, render targets, build-file paths, providerName, and template strings, which must be allowlisted before use in files, shells, sandbox configs, policy presets, or hook resolution.
• pass — 3. Authentication and Authorization: No endpoints, authorization checks, sessions, token validation, or auth enforcement paths are implemented or changed. Auth modes are declarative manifest fields only.
• pass — 4. Dependencies and Third-Party Libraries: No dependency manifests are changed. Tests use existing Vitest and Node built-ins.
• pass — 5. Error Handling and Logging: No production logging or error responses are added. The only production error is duplicate manifest ID rejection, and it includes only the channel id rather than credentials or sensitive values.
• pass — 6. Cryptography and Data Protection: Not applicable — no cryptographic operations, key management, encryption, hashing, or transport-security code are added or modified.
• warning — 7. Configuration and Security Headers: No HTTP endpoints, CORS/CSP, Dockerfiles, workflow permissions, or runtime config are changed. Forward-looking risk remains because the contracts introduce policyPresets, render targets, env-lines, build-args, build-files, and hook references that will need strict allowlists and safe defaults when wired into production.
• warning — 8. Security Testing: Focused tests cover JSON serialization, no function-valued fields, no raw secret serialization, duplicate IDs, registry filtering, and import isolation from side-effect layers. CI is still pending for the current head SHA, so validation completion cannot yet be confirmed.
• warning — 9. Holistic Security Posture: The isolated, type-first design and import-isolation tests are positive for least privilege and trusted-code boundaries. Later runtime consumers must explicitly prevent blueprint tampering, path traversal, secret leakage, policy bypass, unsafe hook execution, and sandbox build/file injection.

Test / E2E status

• Test depth: e2e_required — Unit tests are strong for the isolated type contracts and in-memory registry. Trusted deterministic context classified messaging runtime/infrastructure-adjacent paths as requiring confirmation that E2E Advisor recommendations are fresh for the current head SHA; the E2E Advisor comment currently recommends no required E2E, but its current check is still in progress.
• E2E Advisor: ambiguous

✅ What looks good

• Codebase drift risk appears low: all changed files are new under src/lib/messaging, driftEvidence shows no recent-history/rename hints, and openPrOverlaps is empty.
• The implementation is isolated from existing onboarding, channel lifecycle, rebuild, rendering, credential, policy, sandbox lifecycle, workflow, Dockerfile, and installer code.
• The new type contracts separate secret inputs from config inputs and use TypeScript never fields to prevent secret defaults/state paths.
• The registry is small, in-memory, side-effect free, and covered by tests for duplicate IDs, retrieval, ordering, agent filtering, and empty platform filtering semantics.
• Tests include representative Telegram and WeChat fixtures, JSON round-trips, hook handler references rather than functions, no-raw-secret assertions, and import-isolation checks.
• SPDX headers are present in all newly added source and test files.

Review completeness

• This advisory review used read-only repository inspection plus trusted deterministic context; it did not execute tests, package-manager commands, workflows, or PR-provided scripts.
• CI/status checks are still pending, so required check success for the exact head SHA cannot be fully verified.
• The current E2E Advisor check is in progress; an existing E2E Advisor comment recommends no required E2E jobs but does not include an explicit analyzed SHA.
• The parent issue Refactor messaging integrations into a manifest-first planning architecture #3896 was referenced but its body/comments were not included, so parent acceptance mapping is limited.
• Human maintainer review required: yes

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/messaging/manifest/registry.ts`:
- Line 48: Normalize manifest.id before checking membership against
supportedChannelIds in listAvailable; e.g., compute a normalized id (trim and
lowercase) for manifest.id and use that normalized value in the if check (and
ensure supportedChannelIds contains normalized ids) so mixed-case or whitespace
in manifest.id won't cause false exclusions; update the membership check that
references supportedChannelIds and manifest.id accordingly (symbols:
supportedChannelIds, manifest.id, listAvailable).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ea7fa8ac-df51-483f-9e23-c2c441b6118a

📥 Commits

Reviewing files that changed from the base of the PR and between 1619094 and 17381d2.

📒 Files selected for processing (5)

• src/lib/messaging/index.ts
• src/lib/messaging/manifest/index.ts
• src/lib/messaging/manifest/registry.test.ts
• src/lib/messaging/manifest/registry.ts
• src/lib/messaging/manifest/types.test.ts

[sandl99]

Replaced by #4003, which uses a signed commit on a new branch.

[sandl99]

closed due to unsigned commit