feat(messaging): add manifest type contracts

[sandl99]

Summary

Adds the first phase messaging manifest type contracts under src/lib/messaging. 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
Part of #3896

Changes

• Add the src/lib/messaging type-only 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 fixture-based tests proving JSON round-trip behavior, hook-handler references instead of functions, no raw secret requirement, and no imports from side-effect layers.

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

Ran focused checks for this isolated contract layer:

• npm test -- --project cli src/lib/messaging/manifest/types.test.ts
• npm run typecheck:cli
• npm run lint

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 test suite for messaging channel manifests, including JSON serialization and constraint verification

• New Features

  • Introduced type definitions for messaging channel manifests, authentication modes, inputs, and compiled sandbox plans

• Chores

  • Updated messaging package exports and applied licensing 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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 124cabec-f1f2-4928-899e-17a66644d83e

📥 Commits

Reviewing files that changed from the base of the PR and between 322d339 and 1619094.

📒 Files selected for processing (4)

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

---

📝 Walkthrough

Walkthrough

This PR introduces foundational TypeScript type contracts for the messaging module, defining JSON-serializable schemas for channel manifests and compiled sandbox messaging plans, with representative Telegram and WeChat fixtures and comprehensive validation tests ensuring serialization correctness, absence of function fields, and dependency isolation.

Changes

Messaging Manifest Type Contracts

Layer / File(s)	Summary
Type contracts foundation src/lib/messaging/manifest/types.ts	MessagingSerializableScalar, MessagingSerializableValue, and MessagingSerializableObject establish JSON-compatible primitives; ChannelManifest defines channel identity, authentication, inputs (secret vs config), credentials, render specs (JSON or env-lines), state persistence/hydration, and lifecycle hooks; SandboxMessagingPlan and per-channel plan structures define compiled representations with input references, credential binding plans (using env placeholders, not raw secrets), render fragment plans, and build input plans.
Test validation and fixtures src/lib/messaging/manifest/types.test.ts	Representative Telegram and WeChat ChannelManifest objects with auth configuration, inputs, credentials, render rules, persisted state, and hook definitions; Telegram SandboxMessagingPlan with resolved channel metadata, credentials bound to openshell:resolve:env:... placeholders, and renders; type-level constraint helpers, runtime JSON round-tripping, function-path detection, production file collection, and import-specifier extraction; four test cases validating manifest/plan JSON serialization invariants, absence of raw secret values, no function-valued fields, and module dependency isolation (forbidding imports from gateway, registry, credentials, filesystem, subprocess, and OpenShell adapter layers).
Module exports and wiring src/lib/messaging/manifest/index.ts, src/lib/messaging/index.ts	Added barrel export in manifest module forwarding all types from ./types; updated messaging entry point to re-export all types from ./manifest, exposing the manifest contract surface to consumers.

Sequence Diagram

No sequence diagram applies to this PR. The changes are a set of type definitions, fixtures, and validation tests without multi-component interactions or control flow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

The PR introduces substantial new type definitions and comprehensive test infrastructure across multiple files. The type contract in types.ts is dense (248 lines) with many nested interfaces and union types requiring careful schema review. The test file (340 lines) includes representative fixtures, helper utilities, and four test cases with varying complexity (serialization, secrets, function detection, dependency scanning). The wiring changes are trivial, but understanding the test validation logic and dependency scanning constraints requires careful reading of helper function implementations and assertions.

Poem

In types.ts we craft the shape,
Where manifests and plans escape
The function field's forbidden gate—
No secrets raw, just placeholders straight.
JSON round-trips, tests validate:
Messaging contracts up-to-date! 🐰

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(messaging): add manifest type contracts' clearly and concisely describes the main change of adding TypeScript type contracts for messaging manifests.
Linked Issues check	✅ Passed	The PR comprehensively addresses all coding requirements from issue #3991: defines ChannelManifest and SandboxMessagingPlan types, ensures JSON serializability, validates no function-valued fields, and keeps the module isolated from forbidden imports.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the manifest type contracts, re-exporting types through module entry points, and adding comprehensive validation tests—no unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

_{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: high

Required E2E

• None. No required E2E: the PR introduces TypeScript type-only messaging manifest/plan contracts and unit tests, with export type barrels and no runtime code path changes for onboarding, sandbox lifecycle, credential provider creation, network policy, inference routing, deployment, or live assistant flows.

Optional E2E

• messaging-providers-e2e (medium): Optional confidence check for adjacent live messaging provider behavior: provider attachment, placeholder configuration, no-secret-leak assertions, bridge reachability, and Telegram/Discord/Slack credential rewrite paths. Not merge-blocking because this PR adds type-only contracts and does not wire them into runtime provider planning or sandbox application.

New E2E recommendations

• messaging manifest compiler/applier (high): When these manifest contracts are connected to runtime code, add E2E coverage that starts from a declarative channel manifest, compiles a sandbox messaging plan, applies provider bindings and policy presets, renders agent configuration, and verifies no raw secrets leak into host state or sandbox config.
  • Suggested test: manifest-driven-messaging-plan-e2e
• host-QR and hook-based channel enrollment (medium): The new contract includes hook references and host/in-sandbox QR auth modes, but current E2E coverage focuses on existing provider flows. Add coverage once a hook registry/applier exists to verify hook outputs are persisted only as declared secret/config/build inputs and failure modes such as skip-channel versus abort are honored.
  • Suggested test: messaging-hook-enrollment-e2e

[github-actions]

PR Review Advisor

Recommendation: blocked
Confidence: medium
Analyzed HEAD: 1619094ce69ad13d61dc0af123019f909d32b09a
Findings: 3 blocker(s), 1 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 the provided trusted deterministic context and diff; it did not execute tests or package-manager commands.; CI, CodeRabbit, and E2E recommendation were still pending in the provided status snapshot, so final validation cannot be assessed.; No review-thread state beyond the provided GraphQL nodes and comments was available; CodeRabbit was still processing.; The linked parent issue #3896 was referenced but its clauses were not included in the provided deterministic linked issue payload, so acceptance mapping is limited to issue #3991 and PR body evidence.

Workflow run

Full advisor summary

PR Review Advisor

Base: origin/main
Head: HEAD
Analyzed SHA: 1619094ce69ad13d61dc0af123019f909d32b09a
Recommendation: blocked
Confidence: medium

The type-only messaging manifest layer appears isolated and well covered by focused tests, but merge is blocked by pending CI/E2E recommendation, blocked merge state, and CodeRabbit/review completion gates.

Gate status

• CI: pending — Status rollup for head SHA 1619094 has in-progress checks: cli-parity, E2E recommendation, PR review advisor, CodeQL javascript-typescript, CodeQL python, checks, ShellCheck SARIF, plus CodeRabbit pending.
• Mergeability: fail — GraphQL mergeStateStatus=BLOCKED; REST mergeable_state=blocked; reviewDecision=REVIEW_REQUIRED.
• Review threads: warning — GraphQL reviewThreads nodes are empty, but CodeRabbit posted an in-progress review comment and the CodeRabbit status context is PENDING.
• Risky code tested: pass — No risky code areas detected by path heuristics; changed files are a new type-only messaging manifest module and its tests.

🔴 Blockers

• Required status checks are still pending for the head SHA: The latest head SHA has multiple in-progress or pending contexts, so the PR cannot be treated as validated yet.
  • Recommendation: Wait for all required checks, including CodeQL, cli-parity, checks, ShellCheck SARIF, CodeRabbit, PR review advisor, and E2E recommendation, to complete successfully for 1619094.
  • Evidence: GraphQL statusCheckRollup lists cli-parity, E2E recommendation, PR review advisor, CodeQL javascript-typescript, CodeQL python, checks, ShellCheck SARIF as IN_PROGRESS and CodeRabbit as PENDING.
• Merge state is blocked and review is required: GitHub reports the PR as blocked despite being mechanically mergeable, and reviewDecision is REVIEW_REQUIRED.
  • Recommendation: Do not merge until GitHub mergeStateStatus is no longer BLOCKED and required human review/branch protection conditions are satisfied.
  • Evidence: GraphQL mergeStateStatus=BLOCKED; REST mergeable_state=blocked; reviewDecision=REVIEW_REQUIRED.
• E2E Advisor result is not available for the current head SHA: The deterministic test-depth signal marks this runtime/infrastructure-adjacent messaging module addition as requiring E2E confirmation, but the E2E recommendation check is still in progress and no E2E Advisor comment was found.
  • Recommendation: Wait for the E2E recommendation job and any required E2E jobs it names to pass for head SHA 1619094.
  • Evidence: testDepth.verdict=e2e_required; e2eAdvisorComments=[]; statusCheckRollup has E2E recommendation IN_PROGRESS.

🟡 Warnings

• CodeRabbit review is still in progress: There are no GitHub review-thread nodes in the trusted GraphQL snapshot, but CodeRabbit posted an auto-generated in-progress review comment and the CodeRabbit status is pending.
  • Recommendation: Wait for CodeRabbit to finish and resolve any resulting review comments before merging.
  • Evidence: Issue comment says "Currently processing new changes in this PR"; StatusContext CodeRabbit state=PENDING.

🔵 Suggestions

• Import-isolation test is useful but regex-based (src/lib/messaging/manifest/types.test.ts:328): The test checks production module import specifiers against forbidden fragments using a regular expression over source text. This is reasonable for a type-only first phase, but it can miss dynamic imports or unusual syntax if future production files are added under this module.
  • Recommendation: Keep this test, and consider replacing or supplementing it later with TypeScript compiler API/module graph validation if the messaging module starts containing production logic.
  • Evidence: collectModuleSpecifiers uses /(?:import|export)\s+(?:type\s+)?(?:[^"']*?\s+from\s+)?"'["']/g and then checks forbiddenFragments.

Acceptance coverage

• met — Add src/lib/messaging/manifest/types.ts.: New file src/lib/messaging/manifest/types.ts is added with the manifest and plan type definitions.
• met — Define ChannelManifest with channel identity, supported agents, auth, inputs, credentials, policy, render, state, and hook specs.: src/lib/messaging/manifest/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.: SandboxMessagingPlan and related channel, credential binding, policyPresets, render, buildInputs, and hook reference plan types are defined. Explicit state update plan types are not present as a separate first-class plan field in the diff.
• met — Model secrets as references/placeholders only. Do not store raw secret values in the plan.: Credential specs and binding plans expose sourceInput, providerEnvKey, and placeholder but no value field; test "serializes plan objects without embedding raw secret values" asserts the serialized plan does not contain rawSecret and credentialBindings[0] has no value property.
• met — Add index exports for the new module surface.: src/lib/messaging/index.ts exports type * from "./manifest" and src/lib/messaging/manifest/index.ts exports type * from "./types".
• met — Manifest and plan objects can be JSON-serialized and parsed back without losing required fields.: types.test.ts includes jsonRoundTrip tests for telegramManifest, wechatHookManifest, and telegramPlan and asserts key fields remain present.
• met — Manifest types contain no function-valued fields.: types.test.ts defines FunctionFieldKey compile-time assertions for ChannelManifest and SandboxMessagingPlan and runtime findFunctionPaths checks over representative manifests/plans.
• met — The new module does not import gateway, registry, credentials, filesystem, subprocess, OpenShell adapter, or command/action layers.: Production files added are type-only exports and type declarations. The test "keeps the new production module isolated from side-effect layers" scans production files under src/lib/messaging and forbids gateway, 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 defines telegramManifest, wechatHookManifest, and telegramPlan fixtures. The plan test uses rawSecret="123456:raw-telegram-token" and asserts serialized output does not contain it.
• unknown — Existing onboarding, channel add/remove, rebuild, OpenClaw rendering, and Hermes rendering behavior is unchanged.: Diff only adds new files under src/lib/messaging and no existing workflow files are modified, supporting a low behavior-change risk. However, pending CI/E2E results mean full unchanged behavior has not yet been confirmed for the head SHA.
• 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 new files under src/lib/messaging and does not modify or replace src/lib/sandbox/channels.ts.

Security review

• pass — 1. Secrets and Credentials: No hardcoded real secrets were found in the diff. The new contracts model credentials as sourceInput/providerEnvKey/placeholder references, and tests assert a raw token string is not serialized into plans.
• warning — 2. Input Validation and Data Sanitization: This change is type-only and does not parse untrusted runtime input, execute commands, access paths, or perform SSRF-relevant URL handling. Future compiler/applier code must validate free-form strings such as ids, envKey, handler, statePath, target, build-file path, and template placeholders before using them in files, Docker/build contexts, or command-adjacent flows.
• pass — 3. Authentication and Authorization: No endpoints, authentication checks, authorization decisions, or token validation flows are implemented or modified. Auth modes are declarative only.
• pass — 4. Dependencies and Third-Party Libraries: No package or dependency changes are present. Tests use existing vitest and Node built-ins.
• pass — 5. Error Handling and Logging: No production runtime logic, error responses, or logging are added. Test helper file reads are local to the test environment and do not log sensitive material.
• pass — 6. Cryptography and Data Protection: Not applicable — no cryptographic operations, algorithms, key handling, or data encryption code are added.
• warning — 7. Configuration and Security Headers: No HTTP configuration, CORS, CSP, container image, or security header changes are made. The warning is forward-looking: the new manifest includes policyPresets, render targets, env lines, and build-file/build-arg plan shapes that will require strict allowlists and safe defaults when later wired into production.
• warning — 8. Security Testing: Focused tests cover JSON serialization, no function-valued fields, absence of raw secret fixture requirements, and production import isolation from side-effect layers. E2E/security validation for actual runtime behavior is not yet complete because the E2E recommendation and CI checks are pending.
• warning — 9. Holistic Security Posture: The isolated type-only design is a positive least-privilege first phase and does not directly alter sandbox, credential, network, workflow, or rendering behavior. However, the contracts introduce future surfaces for hooks, build files, env rendering, and policy presets, so downstream compiler/applier work must prevent blueprint tampering, path traversal, secret leakage, and policy bypass.

Test / E2E status

• Test depth: e2e_required — The PR adds messaging manifest and plan contracts intended for future runtime/sandbox/infrastructure flows. Unit tests cover the type-contract layer, serialization, function avoidance, secret placeholder behavior, and import isolation, but required CI and E2E Advisor results for the head SHA are still pending.
• E2E Advisor: missing (not found)
• Required E2E jobs: E2E recommendation
• Missing for analyzed SHA: E2E recommendation

✅ What looks good

• The implementation is isolated to a new src/lib/messaging module surface and does not modify existing onboarding, rebuild, rendering, credential, policy, or sandbox lifecycle code.
• The new public exports are type-only, reducing side-effect and trusted-code-boundary risk in this phase.
• The contracts intentionally distinguish secret inputs from config inputs and prevent secret defaults/state paths at the type level.
• Tests include representative Telegram and WeChat fixtures, JSON round-trip coverage, hook handler references instead of functions, and no-raw-secret assertions.
• The import-isolation test specifically guards against adding production dependencies on gateway, registry, credentials, filesystem, subprocess, OpenShell adapter, and command/action layers.

Review completeness

• This advisory review used the provided trusted deterministic context and diff; it did not execute tests or package-manager commands.
• CI, CodeRabbit, and E2E recommendation were still pending in the provided status snapshot, so final validation cannot be assessed.
• No review-thread state beyond the provided GraphQL nodes and comments was available; CodeRabbit was still processing.
• The linked parent issue Refactor messaging integrations into a manifest-first planning architecture #3896 was referenced but its clauses were not included in the provided deterministic linked issue payload, so acceptance mapping is limited to issue [Messaging] Add manifest type contracts #3991 and PR body evidence.
• Human maintainer review required: yes