# Supen Codex Plugin

This plugin is the Codex-facing capability surface for Supen.

It is not the SupenAgent runtime, not the Feishu app, and not the gateway. SupenAgent should use this plugin to give its underlying Codex access to Supen runtime state and control operations.

## Intended Position

```text
apps/web Agent View      apps/feishu Shupeng      future channels
          \                    |                     /
                         apps/agent
                  SupenAgent runtime and identity
                              |
                    special-purpose Codex
                              |
                    plugins/codex/supen
                              |
                         gateway API
                              |
             computers / daemons / Codex threads
```

## Authentication

There are two intended entrypoints:

- After `supen login`, MCP follows the gateway and renewable session in the local Supen login record. No token environment variable is needed for ordinary interactive use. An explicit `SUPEN_GATEWAY_URL` takes precedence; a login for another gateway is rejected locally without sending its credentials.
- SupenAgent service hosts can explicitly supply `SUPEN_GATEWAY_URL` and a bearer credential such as `SUPEN_GATEWAY_API_KEY` or `SUPEN_ACCESS_TOKEN`. Without an explicit URL or saved login gateway, the default is `https://hub.supen.ai`. Keep credentials out of plugin manifests and command arguments.
- A user-installed Codex plugin should eventually point at a Supen-hosted remote MCP endpoint with OAuth, matching the Cloudflare plugin pattern. That avoids asking users to edit local config files.

Until the hosted OAuth MCP endpoint exists, `.mcp.json` uses the local stdio server as the development entrypoint. It defaults to `https://hub.supen.ai` and does not assume a local gateway exists.

For Cursor Agent seats, install the same bundled Supen MCP server into Cursor's existing
configuration without replacing other servers:

```bash
supen mcp install-supen --target cursor
```

The command preserves existing `~/.cursor/mcp.json` entries and refuses to replace an
existing `supen` entry unless `--force` is supplied. Restart or open a new Cursor Agent
session after installation so it can discover the tools.

## Tool Surface

The MCP implementation exposes a small set of Supen-native tools:

- `supen_list_computers`
- `supen_list_threads`
- `supen_read_thread`
- `supen_list_active_threads`
- `supen_watch_thread_events`
- `supen_start_thread`
- `supen_send_thread_message`
- `supen_interrupt_thread`
- `supen_archive_thread`
- `supen_respond_input`
- `supen_respond_approval`
- `supen_list_dev_servers`
- `supen_list_artifacts`
- `supen_preview_file`
- `team_status`
- `team_report`
- `team_handoff`
- `team_open_thread`

Keep the tool surface close to the gateway's native concepts. Do not add Feishu-specific fields or a parallel task model here.
`team_status` may aggregate live pinned-thread, subagent, and quota summaries, but Gateway/daemon responses remain the source of truth; agents do not self-declare liveness or capacity.

## Lifecycle Bridge

The plugin bundles `SessionStart`, `UserPromptSubmit`, and `Stop` hooks. They send only
coarse lifecycle metadata to the Supen daemon on loopback so tasks started by Codex
Desktop, CLI, or the IDE can report running and idle state without rollout polling.

The bridge is deliberately best-effort: a missing daemon never blocks a Codex turn, and
message bodies, transcripts, tool arguments, and environment variables are not uploaded.

## Boundary

- Gateway owns raw runtime APIs and event relay.
- This plugin exposes those APIs to Codex as tools.
- `apps/agent` owns SupenAgent identity, conversation lifecycle, and runtime host selection.
- Channel apps own channel rendering and ID mapping only.

## SupenAgent Runtime Profile

SupenAgent should run Codex with a curated runtime profile. Do not use a personal Codex
profile that has broad workflow plugins such as `superpowers` installed; those plugins can
consume time before the Supen plugin is even selected. A simple status question should reach
`supen_list_computers` directly because the runtime profile only exposes the supervisor tools
that SupenAgent needs.

The Supen plugin cannot enforce that early selection behavior from `SKILL.md`. `SKILL.md`
only applies after the plugin skill is selected, so latency caused by earlier global
plugin/skill rules must be solved by the SupenAgent host profile.