Core: Reply Engine

[ggondim]

Summary

Implement the Reply Engine — the component that processes the message field from recipient inbound requests, classifies each item (Chat SDK vs A2H), selects the appropriate reply method, and orchestrates rendering and response collection.

Tasks

Message Processing

• Parse message field: normalize single object to 1-item array
• For each item, classify via duck typing: presence of intent = A2H, otherwise = Chat SDK
• Chat SDK path: delegate to ChannelAdapter.renderChatSDK()

A2H Method Selection (decision tree)

• Implement the automatic selection logic:

  Trust layer active? → method 3 (external form)
  Simple AUTHORIZE → method 1 (inline) if buttons, else method 3
  COLLECT closed options → method 1 if selects/buttons, else method 3
  COLLECT free-text (1 field) → method 2 (capture hierarchy: thread → reply → DM → method 3)
  COLLECT multiple fields → method 3
  Multiple A2H intents → method 4 (batch form)
  INFORM → fire-and-forget
  ESCALATE → escalation handler
  

• Method 1 — Inline: delegate to ChannelAdapter.renderA2HInline()
• Method 2 — Text capture: delegate to ChannelAdapter.captureResponse() with capture hierarchy
• Method 3 — External form: generate form URL, send link in channel, await submit
• Method 4 — Batch: group multiple intents into single form page

Response Collection

• Block on A2H intents (except INFORM) until response received
• Return responses to recipient in array, same order as intents
• Handle timeouts for blocking intents (configurable)

Acceptance Criteria

• Single text message → rendered via Chat SDK adapter
• Mixed array (text + AUTHORIZE) → text sent, then AUTHORIZE rendered with correct method
• Method selection matches the decision tree for all intent/capability combinations
• Blocking intents correctly wait for and return responses
• Unit tests for classification, method selection, and array processing

Dependencies

• Core: Data Model, Types & Interfaces #2 (Core: Data Model & Interfaces) — needs all types and channel adapter interface
• Core: Router Implementation #3 (Core: Router) — reply engine is invoked after routing

References

• VISION.md — Reply Methods
• VISION.md — Automatic selection logic
• PLAN.md — Phase 1.5

[claude]

@claude Implement this issue. Follow these steps precisely:

1. Checkout the base branch and create your working branch:
   git fetch origin meta/17 && git checkout meta/17 && git checkout -b claude/17-4-reply-engine
2. Implement all tasks listed in this issue
3. Commit and push your branch:
   git push -u origin claude/17-4-reply-engine
4. Create a PR targeting meta/17:
   gh pr create --base meta/17 --head claude/17-4-reply-engine --title "Core: Reply Engine" --body "fixes Core: Reply Engine #4"

Enable auto-merge on the PR with: gh pr merge --auto --merge

[claude]

Claude finished @claude[bot]'s task in 10m 46s —— View job • claude/issue-4-20260410-2202 • Create PR ➔

---

Implementing Core: Reply Engine

Tasks

• Gather context (VISION.md read, codebase explored)
• Set up working branch (claude/issue-4-20260410-2202)
• Create monorepo structure (packages/core)
• Implement types and interfaces (src/types/index.ts)
• Implement ChannelAdapter interface (src/adapters/channel-adapter.ts)
• Implement message classifier — parse + duck-type (src/engine/message-classifier.ts)
• Implement A2H method selector — full decision tree (src/engine/method-selector.ts)
• Implement response collector — blocking + timeouts (src/engine/response-collector.ts)
• Implement ReplyEngine orchestrator (src/engine/reply-engine.ts)
• Write unit tests — 40+ cases across 3 test files
• Commit and push changes (d086847)
• Create PR targeting meta/17 (requires manual step — see below)

---

What was implemented

New package: packages/core

File	Purpose
src/types/index.ts	A2H intent types, ChatSDK messages, ChannelCapabilities, ReplyContext, engine options
src/adapters/channel-adapter.ts	ChannelAdapter interface — renderChatSDK, renderA2HInline, captureResponse, sendFormLink, handleEscalation
src/engine/message-classifier.ts	Normalize message to array, classify by duck typing (intent field = A2H)
src/engine/method-selector.ts	Full VISION.md decision tree → methods 1 (inline), 2 (text capture), 3 (external form), 4 (batch)
src/engine/response-collector.ts	isBlockingIntent, awaitWithTimeout, collectResponses with per-item error isolation
src/engine/reply-engine.ts	ReplyEngine class — sequential processing, form URL generation, error capture
src/__tests__/	40+ unit tests for classifier, method selector, and engine

Decision tree implemented (from VISION.md):

• Trust layer active → method 3 (always, required for WebAuthn/OTP)
• Multiple A2H intents → method 4 (batch form)
• AUTHORIZE + buttons → method 1 (inline); else → method 3
• COLLECT closed options + buttons/selects → method 1; else → method 3
• COLLECT free-text single field → method 2 (thread → reply → DM → method 3 fallback)
• COLLECT multiple fields → method 3
• INFORM → fire-and-forget (rendered as plain text via renderChatSDK)
• ESCALATE → handleEscalation (fire-and-forget)

---

Create the PR

gh pr create requires additional approval in this environment. Please run:

gh pr create --base meta/17 --head claude/issue-4-20260410-2202 \
  --title "Core: Reply Engine" \
  --body "fixes #4"
gh pr merge --auto --merge

Or use the link below:

|

[claude]

@claude Implement this issue. Follow these steps precisely:

1. Checkout the base branch and create your working branch:
   git fetch origin meta/17 && git checkout meta/17 && git checkout -b claude/17-4-reply-engine
2. Implement all tasks listed in this issue
3. Commit and push your branch:
   git push -u origin claude/17-4-reply-engine
4. Create a PR targeting meta/17:
   gh pr create --base meta/17 --head claude/17-4-reply-engine --title "Core: Reply Engine" --body "fixes Core: Reply Engine #4"

Enable auto-merge on the PR with: gh pr merge --auto --merge

[claude]

Claude finished @claude[bot]'s task in 14m 6s —— View job • claude/issue-4-20260410-2205 • Create PR ➔

---

Implementing Core: Reply Engine

Tasks

• Gather context (read VISION.md, analyzed data model and reply methods)
• Set up working branch (claude/issue-4-20260410-2205)
• Create monorepo structure (root package.json, tsconfig.json)
• Create core package types (A2HMessage, ChatSDKMessage, ChannelAdapter, FormStore, TimeoutError, etc.)
• Implement message parser (parseMessage, isA2HItem, classifyAll)
• Implement A2H method selector (full decision tree from VISION.md)
• Implement reply methods 1–4 + INFORM/ESCALATE handlers
• Implement response collector with timeout (withTimeout, collectSingle, collectBatch)
• Write unit tests (30+ test cases across parser, selector, and full engine)
• Commit and push changes
• Create PR targeting meta/17 (see link below — gh pr create requires additional permissions)
• Enable auto-merge (requires PR to be created first)

Implementation

14 files created, 1 989 insertions:

File	Purpose
packages/core/src/types/index.ts	All types: A2HMessage, ChatSDKMessage, ChannelAdapter, FormStore, ReplyContext, TimeoutError, envelope types
packages/core/src/reply-engine/parser.ts	parseMessage (normalise → array), isA2HItem (duck typing), classifyAll
packages/core/src/reply-engine/selector.ts	selectA2HMethod — full decision tree, deriveCaptureMode
packages/core/src/reply-engine/methods.ts	executeMethod1–4, executeInform, executeEscalate
packages/core/src/reply-engine/collector.ts	withTimeout, collectSingle (method 2→3 fallback), collectBatch
packages/core/src/reply-engine/index.ts	processReply — public orchestrator
packages/core/src/reply-engine/__tests__/parser.test.ts	Parser unit tests
packages/core/src/reply-engine/__tests__/selector.test.ts	Decision tree tests (all branches)
packages/core/src/reply-engine/__tests__/reply-engine.test.ts	Integration tests (mixed array, method 4 batch, trust layer, timeout, etc.)

Decision tree implemented:

Trust layer active?          → method 3
Multiple blocking intents?   → method 4 (batch form)
Simple AUTHORIZE             → method 1 if buttons, else method 3
COLLECT – closed options     → method 1 if select/buttons, else method 3
COLLECT – free-text 1 field  → method 2 (thread→reply→DM→method 3)
COLLECT – multiple fields    → method 3
INFORM                       → fire-and-forget (sendMessage)
ESCALATE                     → handleEscalation

·

[claude]

@claude Implement this issue. Follow these steps precisely:

1. Checkout the base branch and create your working branch:
   git fetch origin meta/17 && git checkout meta/17 && git checkout -b claude/17-4-reply-engine
2. Implement all tasks listed in this issue
3. Commit and push your branch:
   git push -u origin claude/17-4-reply-engine
4. Create a PR targeting meta/17:
   gh pr create --base meta/17 --head claude/17-4-reply-engine --title "Core: Reply Engine" --body "fixes Core: Reply Engine #4"

Enable auto-merge on the PR with: gh pr merge --auto --merge

[claude]

Claude finished @claude[bot]'s task in 9m 12s —— View job • claude/issue-4-20260410-2207 • Create PR ➔

---

Implementing Core: Reply Engine

Tasks

• Gather context (read VISION.md, understand architecture)
• Set up working branch (claude/issue-4-20260410-2207)
• Create monorepo structure (root + core package)
• Implement types and interfaces (Data Model)
• Implement message normalizer and classifier
• Implement A2H method selection decision tree
• Implement reply methods (inline, capture, external form, batch)
• Implement response collection with blocking and timeouts
• Write unit tests (classification, method selection, array processing)
• Commit and push changes
• Create PR

Summary

Implemented the full Reply Engine in packages/core. Key files:

File	Purpose
src/types/index.ts	Full data model — ChatSDKMessage, A2HMessage, ChannelAdapter, ReplyEngineConfig, all supporting types
src/reply-engine/normalizer.ts	Normalize single object → 1-item array
src/reply-engine/classifier.ts	Duck-typing classification (intent field present = A2H, otherwise Chat SDK)
src/reply-engine/method-selector.ts	Decision tree for methods 1–4, capture hierarchy for method 2
src/reply-engine/response-collector.ts	TimeoutError, withTimeout(), ResponseRegistry (pending form submissions)
src/reply-engine/index.ts	ReplyEngine class orchestrating all of the above

Tests cover all acceptance criteria: classification, method selection across all intent/capability combinations, mixed arrays (text + A2H), method 4 batching, trust layer, timeouts, escalation handler.

Note on methods 3 & 4 (external form): The engine sends the form link and blocks via ResponseRegistry. The form server (future packages/server) resolves pending responses by calling engine.registry.submit(turnId, response). This is the integration point documented in the ReplyEngine JSDoc.

|