---
name: digital-twin
description: Set up, inspect, or troubleshoot the hosted EzWebex digital twin bot that listens for Webex mentions and runs work in the hosted workspace.
---

# EzWebex Digital Twin

Use this skill when the user asks to create, set up, run, stop, inspect, or troubleshoot an EzWebex digital twin, Paddy-style bot, personal Webex bot, or always-on Webex watcher.

## Core Model

- Digital twins are hosted-only. Do not set up, start, validate, or use a local Mac digital-twin runner.
- If the user is in local Codex and asks to create or run a digital twin, direct them to the hosted EzWebex dashboard and tell them to deploy/manage the bot there.
- The same EzWebex plugin package runs locally and in the hosted workspace. Local Codex uses the Webex, GitHub, Confluence, dashboard, and hosted handoff tools; hosted EzWebex additionally runs the always-on digital-twin listener.
- Hosted workspace pods set `EZWEBEX_HOSTED_WORKSPACE=1`. Digital-twin lifecycle tools are only expected to execute in that environment.
- Each user owns their Webex bot identity and bot token. The token is captured through the hosted dashboard and stored in the user's hosted workspace namespace.
- The hosted listener classifies incoming Webex events before actioning them. Bot mentions are always eligible; owner mentions and all-space processing require per-user feature flags.
- Classification first decides whether a message should be actioned, then classifies actioned work as READ or WRITE.
- By default, READ and WRITE work both create a Command Center task in `awaiting_handoff` with `Open in Codex`. Desktop Codex completes the task.
- READ work runs hosted Codex directly only when that user has `headlessReadDrafts` enabled; those draft replies still require owner approval.
- Integration-assisted task enrichment is available only when `integrationContextEnrichment` is enabled.
- `Open in Codex` uses a `codex://new?prompt=...` deeplink and a hosted handoff URL/job id. Desktop Codex loads the full task context from the hosted job API through the EzWebex plugin.
- Do not post a final public Webex reply directly from Codex. The hosted approval card controls whether EzWebex replies to the original request.

## Tools

- `webex-digital-twin-status`: safe to call locally; it reports hosted-only guidance without reading or starting local runner state.
- `webex-digital-twin-stop`: hosted/internal lifecycle tool. Do not call it from local Codex.
- `webex-digital-twin-create-bot`, `webex-digital-twin-setup`, `webex-digital-twin-run`, and `webex-digital-twin-configure-triggers` are hosted-workspace lifecycle tools. Do not call them from local Codex; local calls are expected to return hosted-only guidance.
- `webex-digital-twin-action-handoff` and `webex-digital-twin-submit-result` are usable from Desktop Codex when opening a hosted handoff. They load and update the hosted task rather than a local runner job store.

## Hosted Bot Setup

When the user needs a bot:

1. Send them to the hosted EzWebex dashboard.
2. Have them sign in with Webex and initialize their workspace.
3. Have them use the dashboard's digital-twin setup step to create/connect a Webex bot and store the one-time bot token in the hosted namespace.
4. Verify with the dashboard or `webex-digital-twin-status` from the hosted workspace that the listener is running.
5. Mention the bot in Webex to validate that the hosted listener creates a Command Center task.

Do not ask the user to paste a Webex bot token into local chat. Do not capture, print, summarize, screenshot, or log bot tokens.

## Setup Safety

The Webex Developer Portal confirmation page shows both a Bot access token and a Bot ID. These are not interchangeable:

- Capture the Bot access token only inside the hosted dashboard setup flow.
- Do not pass the Developer Portal Bot ID as `botPersonId`. That value is an application/bot ID, but Webex message mentions use the bot's person ID.
- Prefer omitting `botPersonId` and `botEmail` during setup when a real bot token is available. The hosted setup validates the token with the bot's `/people/me` profile and discovers the correct `botPersonId` and bot email.
- If `botPersonId` must be supplied manually, get it from the bot token's `/people/me` response or from the `mentionedPeople` value on a Webex message that truly mentions the bot.
- After setup, verify `webex-digital-twin-status` shows `hasBotToken: true`, `botTokenStorage`, and a `botPersonId` that can match Webex `mentionedPeople` entries. A configured application ID will not trigger handoffs.

## Run Behavior

After hosted setup, verify:

- `configured` is true.
- The token is shown only as `hasBotToken` and `botTokenStorage`.
- The runner state is `listening`.
- The hosted listener deployment is always-on.
- The queue space and job store paths are present.
- No local runner, local twin job store, or local opener is required for Cloud listener operation or hosted task handoff.

For a manual validation:

1. Mention the bot in a test Webex space.
2. Confirm the request creates an `awaiting_handoff` task in Command Center with `Open in Codex`.
3. Confirm Desktop Codex opens with the handoff prompt and can load full task context through the EzWebex plugin.
4. Confirm flagged READ users still get hosted draft replies and approval, decline, and edit actions work from Webex.
