PR #78358: fix(imessage): honor per-group systemPrompt

• Repository: openclaw/openclaw
• Author: bitloi
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78358

Description (problem / solution / changelog)

Summary

• Problem: iMessage group configs rejected/ignored groups.*.systemPrompt, so configured per-group prompts never reached GroupSystemPrompt.
• Why it matters: iMessage operators could not use the same trusted per-group prompt behavior already available in other group-capable channels.
• What changed: added iMessage group systemPrompt config support, resolved iMessage group ids from chat_id, chat_guid, chat_identifier, and "*", and forwarded trusted group prompts into inbound group contexts.
• What did NOT change (scope boundary): DMs do not receive group prompts; no outbound behavior, network behavior, auth, or tool execution surface changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #78285
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: iMessage group-level systemPrompt is now accepted by config validation and forwarded as GroupSystemPrompt for group inbound contexts.

• Real environment tested: local OpenClaw checkout on Linux with Node 24.11.0 and pnpm 10.33.2.

• Exact steps or command run after this patch: ran a local OpenClaw production inbound-path smoke with node --import tsx -e importing extensions/imessage/src/monitor/inbound-processing.ts, using a redacted iMessage config with channels.imessage.groups["iMessage;+;chat-family"].systemPrompt, building a group inbound context and a direct inbound context.

• Evidence after fix: copied console output from the local runtime smoke:

  {
    "group": {
      "chatType": "group",
      "to": "chat_id:42",
      "groupSystemPrompt": "Use the family group style.",
      "sessionKey": "agent:main:imessage:group:42"
    },
    "direct": {
      "chatType": "direct",
      "groupSystemPromptPresent": false
    }
  }

• Observed result after fix: the production iMessage inbound context builder populated GroupSystemPrompt for the raw chat_guid group and did not expose a group prompt on the direct-message context.

• What was not tested: live iMessage transport with a real Messages database/event.

• Before evidence: source-level issue evidence in #78285 shows iMessage had no systemPrompt config field and never set GroupSystemPrompt.

Root Cause (if applicable)

• Root cause: iMessage group config schema/types did not include systemPrompt, and the inbound context builder did not resolve configured group prompts or set GroupSystemPrompt.
• Missing detection / guardrail: no iMessage schema or inbound-context regression test covered per-group prompt injection.
• Contributing context: current iMessage group matching primarily used numeric chat_id; the issue requested BlueBubbles-style chat_guid keys, so the fix defines and tests explicit iMessage group id candidate matching.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • extensions/imessage/src/config-schema.test.ts
  • extensions/imessage/src/monitor.gating.test.ts
  • src/config/group-policy.test.ts
• Scenario the test should lock in: iMessage group systemPrompt is accepted and forwarded for exact/wildcard group matches, including raw chat_guid; DMs do not get group prompts.
• Why this is the smallest reliable guardrail: tests cover config parsing plus the inbound envelope builder without requiring live Messages transport.
• Existing test that already covers this (if any): none.

User-visible / Behavior Changes

New optional config field: channels.imessage.groups.<group-id>.systemPrompt.

Supported iMessage group keys include numeric chat_id, chat_id:<id>, raw chat_guid, chat_guid:<guid>, raw chat_identifier, chat_identifier:<identifier>, and "*".

Diagram (if applicable)

Before:
iMessage group message -> inbound context -> GroupSystemPrompt unset

After:
iMessage group message -> resolve groups.<id>.systemPrompt -> inbound context -> GroupSystemPrompt set

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 24.11.0, pnpm 10.33.2
• Model/provider: N/A
• Integration/channel (if any): iMessage
• Relevant config (redacted): tests cover channels.imessage.groups.<id>.systemPrompt

Steps

1. Configure an iMessage group with systemPrompt.
2. Build the inbound dispatch context for a group message matching that group id.
3. Observe GroupSystemPrompt on the finalized context.

Expected

• GroupSystemPrompt contains the configured prompt for matching group messages.
• wildcard prompt applies for other groups.
• DMs omit group prompts.

Actual

• Matches expected in the local runtime smoke and regression tests.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: local production inbound-path smoke for raw chat_guid; config schema acceptance; exact chat_id; raw chat_guid; wildcard fallback; DM omission; shared group-policy candidate matching; generated config metadata/docs baseline.
• Edge cases checked: exact prompt wins over wildcard; exact empty string suppresses wildcard; DM path ignores group prompts.
• What you did not verify: live iMessage transport/database event.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (Yes)
• Migration needed? (No)

The config change is additive and optional.

Risks and Mitigations

• Risk: iMessage group identifier semantics differ across event sources.
  • Mitigation: candidate matching supports chat_id, chat_guid, chat_identifier, prefixed forms, and wildcard, with docs and regression tests.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/.generated/config-baseline.sha256 (modified, +3/-3)
• docs/channels/imessage.md (modified, +23/-0)
• extensions/imessage/src/config-schema.test.ts (modified, +16/-0)
• extensions/imessage/src/monitor.gating.test.ts (modified, +74/-0)
• extensions/imessage/src/monitor/inbound-processing.ts (modified, +87/-5)
• src/config/bundled-channel-config-metadata.generated.ts (modified, +10/-10)
• src/config/group-policy.test.ts (modified, +31/-0)
• src/config/group-policy.ts (modified, +18/-4)
• src/config/types.imessage.ts (modified, +1/-0)
• src/config/zod-schema.providers-core.ts (modified, +1/-0)

PR #78357: fix(imessage): honor per-group systemPrompt

• Repository: openclaw/openclaw
• Author: hexven0m
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78357

Description (problem / solution / changelog)

Summary

• Problem: iMessage group configs ignored groups.*.systemPrompt, so per-group prompts were never applied to inbound contexts.
• Why it matters: iMessage operators could not use consistent per-group prompt behavior available in other group-capable channels.
• What changed: Added support for systemPrompt in iMessage group configs, implemented group identifier resolution (chat_id, chat_guid, chat_identifier, "*"), and forwarded matched prompts into GroupSystemPrompt for inbound group contexts.
• What did NOT change (scope boundary): Direct messages do not receive group prompts; no changes to outbound behavior, networking, auth, or tool execution.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #78285
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: iMessage group-level systemPrompt is now accepted and correctly injected into inbound group contexts as GroupSystemPrompt.

• Real environment tested: Local OpenClaw setup (Linux), Node 24.11.0, pnpm 10.33.2.

• Exact steps or command run after this patch:

  1. Configure channels.imessage.groups["iMessage;+;chat-family"].systemPrompt.

  2. Run inbound processing via:

     node --import tsx -e "import 'extensions/imessage/src/monitor/inbound-processing.ts'"

  3. Build both group and direct inbound contexts.

• Evidence after fix:

{
  "group": {
    "chatType": "group",
    "to": "chat_id:42",
    "groupSystemPrompt": "Use the family group style.",
    "sessionKey": "agent:main:imessage:group:42"
  },
  "direct": {
    "chatType": "direct",
    "groupSystemPromptPresent": false
  }
}

• Observed result after fix: Group contexts include the configured GroupSystemPrompt; direct-message contexts correctly omit it.
• What was not tested: Live iMessage transport or Messages database events.
• Before evidence: Issue #78285 shows missing schema support and no GroupSystemPrompt assignment.

Root Cause (if applicable)

• Root cause: iMessage group config schema lacked systemPrompt, and inbound processing did not resolve or apply group-level prompts.
• Missing detection / guardrail: No regression tests covered iMessage-specific group prompt injection.
• Contributing context: Group matching previously relied mainly on numeric chat_id, lacking support for other identifiers like chat_guid.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:

  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient

• Target test or file:

  • extensions/imessage/src/config-schema.test.ts
  • extensions/imessage/src/monitor.gating.test.ts
  • src/config/group-policy.test.ts

• Scenario the test should lock in:

  • systemPrompt is accepted and applied for:

    • Exact group matches
    • chat_guid-based matches
    • Wildcard ("*" ) fallback

  • Direct messages do not receive group prompts

• Why this is the smallest reliable guardrail: Covers config parsing and inbound context construction without requiring live iMessage integration.

• Existing test that already covers this (if any): None

User-visible / Behavior Changes

• New optional config field: channels.imessage.groups.<group-id>.systemPrompt

• Supported group identifiers:

  • chat_id or chat_id:<id>
  • chat_guid or chat_guid:<guid>
  • chat_identifier or chat_identifier:<identifier>
  • "*" (wildcard)

Diagram (if applicable)

Before:
iMessage group message -> inbound context -> GroupSystemPrompt unset

After:
iMessage group message -> match groups.<id>.systemPrompt -> inbound context -> GroupSystemPrompt set

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 24.11.0, pnpm 10.33.2
• Model/provider: N/A
• Integration/channel (if any): iMessage
• Relevant config (redacted): channels.imessage.groups.<id>.systemPrompt

Steps

1. Configure an iMessage group with systemPrompt
2. Process an inbound group message matching that group
3. Inspect the resulting inbound context

Expected

• Matching group messages include GroupSystemPrompt
• Wildcard applies when no exact match exists
• Direct messages exclude group prompts

Actual

• Matches expected behavior in local runtime and tests

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: Config parsing, exact chat_id match, raw chat_guid match, wildcard fallback, DM exclusion, inbound context population.

• Edge cases checked:

  • Exact match overrides wildcard
  • Empty string disables wildcard fallback
  • DM contexts ignore group prompts

• What you did not verify: Live iMessage transport/database events

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? Yes
• Migration needed? No

The change is additive and optional.

Risks and Mitigations

• Risk: Variation in iMessage group identifiers across event sources

  • Mitigation: Flexible candidate matching (chat_id, chat_guid, chat_identifier, prefixed forms, wildcard) with regression test coverage and documentation

Changed files

• docs/.generated/config-baseline.sha256 (modified, +3/-3)
• docs/channels/imessage.md (modified, +23/-0)
• extensions/imessage/src/config-schema.test.ts (modified, +16/-0)
• extensions/imessage/src/monitor.gating.test.ts (modified, +74/-0)
• extensions/imessage/src/monitor/inbound-processing.ts (modified, +87/-5)
• src/config/bundled-channel-config-metadata.generated.ts (modified, +10/-10)
• src/config/group-policy.test.ts (modified, +31/-0)
• src/config/group-policy.ts (modified, +18/-4)
• src/config/types.imessage.ts (modified, +1/-0)
• src/config/zod-schema.providers-core.ts (modified, +1/-0)