Microsoft Teams Channel Integration

[Proxicon]

Microsoft Teams Channel Integration

Summary

This PR adds Microsoft Teams as a first-class Netclaw communication channel and upstreams the Teams implementation that has been developed and validated in the Proxicon fork.

It implements the current delivery scope defined by the Microsoft Teams roadmap:

• Phase 1 — Teams Channel Integration
• Phase 1.1 — Teams Runtime Modernization

Roadmap: #1946 — Microsoft Teams Roadmap and Architecture Strategy

This also resolves the original Teams channel request:

Closes #1401

The implementation follows the same architectural principle as Netclaw's other channels: Microsoft-specific transport concerns remain at the channel boundary, while sessions, orchestration, tools, approvals, memory, reminders, and policy remain Netclaw-owned and platform-agnostic.

---

Roadmap alignment

Phase 1 — Teams Channel Integration

This PR establishes Teams as a stable Netclaw transport with the core functionality required by the Phase 1 roadmap.

It includes:

• authenticated Microsoft Teams ingress
• personal chat support
• Group Chat support
• Team/channel post support
• channel thread routing
• mention handling and established-thread continuation
• conversation-to-session mapping
• durable conversation bindings
• restart recovery
• duplicate suppression
• outbound replies
• canonical thread replies
• progress/update delivery
• proactive reminder delivery
• interactive tool approvals through Adaptive Cards
• attachment classification and safe image ingress
• fail-closed transport and ACL behavior
• operational configuration and diagnostics
• Teams application packaging and deployment guidance
• TUI-based Teams access and destination management

The result is that a Teams conversation can participate in the existing Netclaw session pipeline rather than introducing a Teams-specific orchestration model.

Phase 1.1 — Teams Runtime Modernization

The implementation also lands the modernization baseline described by Phase 1.1 instead of introducing a legacy transport that would immediately require replacement.

The Teams integration uses the current Microsoft Teams SDK 2.x line; the fork is currently pinned to Microsoft Teams SDK 2.1.0.

The runtime design includes:

• ASP.NET Core-native Teams hosting at the daemon boundary
• typed Teams activity handling
• application/tenant authentication isolated at the transport boundary
• SDK-specific types kept out of Netclaw's core actor/session contracts
• immutable Netclaw-owned translation contracts between Teams and the runtime
• typed operational telemetry and integration with the existing observability model
• Microsoft Graph-backed directory/discovery helpers for operator configuration where required

This preserves Phase 1 behavior while giving the Teams adapter a modern runtime foundation.

Graph usage in this PR is limited to Teams administration/discovery scenarios such as resolving users, channels, and Group Chats. It does not introduce the Microsoft 365 workload automation planned for Phase 2.

---

Channel behavior

Personal conversations

Personal Teams chats are mapped into durable Netclaw conversation/session bindings.

The implementation provides:

• authenticated sender and tenant validation
• explicit allowed-user policy
• canonical user identity handling
• durable activity fingerprints
• duplicate suppression
• session continuity across process restarts
• normal Netclaw replies and proactive delivery

Teams channels and threads

Channel conversations preserve Teams threading semantics.

The adapter distinguishes the canonical channel root from replies and maps the conversation into a stable Netclaw session.

Supported behavior includes:

• Team and channel ACLs
• bot mention requirements for new roots
• continuation of an already-established thread without requiring every subsequent message to mention the bot
• canonical root/thread routing
• replies returned to the correct Teams thread
• independent sessions for separate roots
• reminder delivery back into the originating conversation

The channel adapter does not move thread/session semantics into the Netclaw core; it translates Teams-specific addressing into the existing channel/session model.

Group Chats

Group Chat support is included as a separately controlled ingress mode.

Operators can:

• enable or disable Group Chat ingress
• search Group Chats by name
• discover chats through bounded Microsoft Graph metadata queries
• select and persist canonical Group Chat IDs
• remove previously allowed Group Chats
• preserve saved chat IDs when ingress is temporarily disabled

Group Chat discovery is administrative only. Display names never grant access; persisted canonical IDs remain authoritative.

Friendly discovery may use the relevant Graph application permissions, while direct canonical-ID configuration remains available independently of discovery.

---

Approvals

Teams supports Netclaw's existing approval model through Adaptive Cards.

Approval actions are translated back into the normal Netclaw approval pipeline rather than creating a Teams-specific authorization mechanism.

The implementation includes:

• interactive approval cards
• typed approval action routing
• preservation of Netclaw approval keys/options
• explicit decision styling
• bounded/fail-closed action processing

Authorization remains owned by Netclaw.

---

Reminders and proactive delivery

The Teams channel supports proactive output after the original inbound request has completed.

This includes:

• durable destination state
• reminder delivery to personal chats
• reminder delivery to approved channel threads
• restart recovery
• stale-destination protection
• duplicate/no-resend behavior after successful delivery
• isolation between independent channel roots

The Teams gateway receives generic Netclaw reminder/output messages; scheduling itself remains channel-independent.

---

Attachments and images

Teams attachment handling is deliberately fail-closed.

The implementation distinguishes safe rendering metadata from actual file/reference attachments and validates supported image ingress before admitting it to the model/session pipeline.

The attachment path includes:

• structural attachment classification
• rejection of unsupported or ambiguous reference shapes
• bounded download and verification budgets
• partial-file cleanup
• safe retry behavior for stalled image transfers
• bounded image batching/concurrency
• MIME and filename validation
• safe diagnostics that avoid leaking URLs, tokens, payloads, or raw provider exceptions

Normal text handling remains independent from rejected attachment content where policy allows it.

---

Access control and safety

The Teams adapter is disabled by default and uses explicit configuration before accepting traffic.

The access model includes:

• tenant validation
• allowed-user controls
• allowed-Team controls
• allowed-channel controls
• allowed Group Chat controls
• canonical ID validation
• mention policy
• audience/trust mapping
• fail-closed ambiguous configuration handling
• request size limits
• ingress rate limiting
• attachment validation
• duplicate prevention

Microsoft-specific policy is kept at the channel boundary wherever possible. Existing Netclaw tool, audience, approval, and trust policies remain authoritative after a Teams message enters the session pipeline.

---

Operator configuration

The Netclaw TUI includes Teams configuration and access-management workflows.

Operators can manage:

• Teams enablement/configuration
• users/principals
• Teams and channels
• Group Chats
• Group Chat ingress
• canonical destination IDs
• directory-backed discovery/search

Group Chat search supports partial/full chat-name matching, bounded paging, automatic continuation, deduplication, cancellation, and canonical-ID persistence.

The implementation intentionally distinguishes friendly discovery from authorization: a directory or Graph search result does not itself grant access.

---

Teams application package

The contribution includes the Teams application packaging/operations work required to deploy the bot into a tenant.

The package aligns the Teams application identity with the configured Entra application and supports the capabilities required by the channel integration.

Operational documentation covers configuration and deployment expectations without moving tenant-specific credentials or identities into source control.

---

Architecture

A key design goal is to prevent Teams from leaking deeply into Netclaw's core.

At a high level:

Microsoft Teams
      |
      v
ASP.NET Core / Teams SDK 2.x boundary
      |
      v
Teams activity translation
      |
      v
Immutable Netclaw-owned channel contracts
      |
      v
Teams conversation/binding actors
      |
      v
Existing Netclaw session pipeline
      |
      +--> model/tool execution
      +--> approvals
      +--> reminders
      +--> memory
      +--> policy
      |
      v
Teams output adapter
      |
      v
Microsoft Teams

The Teams SDK is therefore an edge dependency rather than an orchestration dependency.

This is consistent with the roadmap principle that Teams should become a first-class channel without replacing Netclaw's existing session, memory, approval, orchestration, or tool execution models.

---

Validation

The Teams work has been developed incrementally in the Proxicon fork with dedicated regression coverage for the transport, actors, persistence, configuration, TUI, approvals, reminders, attachments, Graph-backed discovery, and application package.

Development validation has included combinations of:

• focused Teams test suites
• full Netclaw solution builds/tests
• actor and daemon regression suites
• configuration/TUI tests
• native TUI smoke tests
• Teams package/schema validation
• strict OpenSpec validation
• repository formatting/header/diff checks
• live tenant validation of the supported Teams conversation paths during development

The implementation has also been repeatedly synchronized with upstream dev during development so that the final contribution is based on current upstream architecture rather than an isolated long-lived fork.

---

Scope boundaries

This PR implements Phase 1 and the Phase 1.1 runtime modernization baseline from #1946.

It intentionally does not implement the later roadmap phases.

Not included:

• general Microsoft 365 workload access
• delegated Outlook/Calendar/OneDrive/SharePoint automation
• broad Microsoft Graph tool access for agents
• Microsoft Agent 365 identity/governance integration
• Agent 365 lifecycle/governance features

Those remain Phase 2 and Phase 3 roadmap work.

---

Related issues

• Implements Phase 1 — Teams Channel Integration of [EPIC] Microsoft Teams Roadmap and Architecture Strategy #1946
• Implements Phase 1.1 — Teams Runtime Modernization of [EPIC] Microsoft Teams Roadmap and Architecture Strategy #1946
• Closes Add Support for Microsoft Teams #1401 — Add Support for Microsoft Teams

[Proxicon]

Related PR for the Netclaw-website: netclaw-dev/netclaw-website#122

Apologies about the unsigned commits @Aaronontheweb - Let me know how you would like to proceed. Its strange coming from the same dev env, like hit & miss.

Also worthy to note, Teams channel ordering will conflict with Telegram on : #1905