termpilot-plugin 0.1.0__tar.gz

termpilot_plugin-0.1.0/.gitignore

@@ -0,0 +1,231 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+.DS_Store
+Thumbs.db
+*.tmp
+*.swp
+.vscode/
+.idea/
+.worktrees/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Agents
+.agents/
+
+# specify
+.specify/

termpilot_plugin-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

termpilot_plugin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blizhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

termpilot_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.5
+Name: termpilot-plugin
+Version: 0.1.0
+Summary: Give ChatGPT eyes and hands in your terminal
+Project-URL: Homepage, https://github.com/blizhan/termpilot
+Project-URL: Repository, https://github.com/blizhan/termpilot
+Project-URL: Issues, https://github.com/blizhan/termpilot/issues
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: iterm2<3,>=2.2
+Requires-Dist: mcp<3,>=2
+Description-Content-Type: text/markdown
+
+# TermPilot
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+TermPilot gives ChatGPT a structured way to inspect and act on the iTerm2
+sessions that are already open on a Mac. It is designed for ChatGPT Classic
+with macOS Work with Apps: Work with Apps provides the terminal context, and
+TermPilot provides four MCP tools for session discovery, bounded inspection,
+and explicit command execution.
+
+## Prerequisites
+
+- macOS with iTerm2 running.
+- Python 3.13 and [uv](https://docs.astral.sh/uv/).
+- iTerm2's Python API enabled. See the [iTerm2 Python API
+  documentation](https://iterm2.com/python-api/).
+- iTerm2 [Shell Integration](https://iterm2.com/documentation-shell-integration.html)
+  installed in each shell where `run_command` will be used. Shell Integration
+  provides the prompt state and command completion metadata needed for safe
+  execution.
+
+## Install and run
+
+Install from PyPI with `uv`:
+
+```bash
+uv tool install termpilot-plugin
+termpilot
+```
+
+Or run directly without installing:
+
+```bash
+uvx --from termpilot-plugin termpilot
+```
+
+For development from the repository root:
+
+```bash
+uv sync
+uv run termpilot
+```
+
+`termpilot` speaks MCP over stdio. It keeps stdout reserved for MCP messages;
+diagnostic logging is sent to stderr. A local MCP client can run the PyPI package
+directly with a configuration like this:
+
+```json
+{
+  "mcpServers": {
+    "termpilot": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "termpilot-plugin",
+        "termpilot"
+      ]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose | Access |
+| --- | --- | --- |
+| `list_sessions` | List accessible sessions and their IDs, labels, host, user, cwd, current marker, and readiness | Read-only |
+| `get_current_session` | Resolve the iTerm2 session currently in focus | Read-only |
+| `read_terminal` | Read bounded visible content from one exact `session_id` | Read-only |
+| `run_command` | Send an explicitly supplied command to one exact `session_id` and optionally wait for completion | Mutating |
+
+The normal flow is:
+
+1. Call `get_current_session` or `list_sessions`.
+2. Use the returned exact `session_id` with `read_terminal` when inspection is useful.
+3. Call `run_command` only after the user has explicitly requested the command.
+4. Review the correlated session ID, command, status, exit code, and bounded output.
+
+## Safety behavior
+
+- `run_command` requires an exact `session_id`; labels and fuzzy matches are
+  never used as a write target.
+- A missing, closed, inaccessible, or ambiguous target fails closed and is
+  never redirected to another session.
+- Terminal content, command history, titles, and prior tool output are
+  observation data. They are never copied into a command request implicitly.
+- Commands are sent through the existing iTerm2 session with broadcast input
+  suppressed where the API supports it. TermPilot does not create a new shell,
+  window, or SSH connection.
+- Command execution requires a verified normal shell prompt. Busy or
+  interactive sessions are rejected without sending text.
+- A timeout stops waiting for the result; it does not claim that the shell
+  command was cancelled.
+
+## Validation
+
+Run the automated checks with:
+
+```bash
+uv run pytest
+uv run ruff check src tests
+uv run ruff format --check src tests
+```
+
+The live test is opt-in and only checks a running iTerm2 instance's session
+inventory:
+
+```bash
+TERMPILOT_LIVE_ITERM2=1 uv run pytest tests/integration/test_iterm2_live.py -q
+```
+
+For the complete manual inspect → act → inspect scenarios, see
+[`specs/001-chatgpt-terminal-actions/quickstart.md`](specs/001-chatgpt-terminal-actions/quickstart.md).
+
+## ChatGPT connection
+
+ChatGPT cannot use a local stdio process directly. TermPilot can connect the
+same MCP server through [OpenAI Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
+using the official `tunnel-client` managed runtime.
+
+### 1. Install `tunnel-client`
+
+On macOS with Homebrew:
+
+```bash
+brew install openai/tools/tunnel-client
+tunnel-client --version
+```
+
+TermPilot does not bundle or pin `tunnel-client`; it uses the binary available
+on `PATH`.
+
+### 2. Create a tunnel and runtime key
+
+Open the OpenAI Platform pages exposed by `tunnel-client help quickstart`:
+
+- [Tunnels management](https://platform.openai.com/settings/organization/tunnels):
+  create a tunnel and copy its `tunnel_...` ID.
+- [Runtime API keys](https://platform.openai.com/settings/organization/api-keys):
+  create the key used by the long-running tunnel runtime. The principal that
+  creates/uses it needs **Tunnels Read + Use** for the target tunnel.
+- [Admin API keys](https://platform.openai.com/settings/organization/admin-keys)
+  are only needed for tunnel CRUD through `tunnel-client admin ...`; do not use
+  an admin key as the long-running runtime key.
+
+If you prefer to create the tunnel from the CLI, configure an admin key first
+and use the native `tunnel-client` tunnel-management command (at least one
+organization or workspace scope is required):
+
+```bash
+export OPENAI_ADMIN_KEY="sk-admin-..."
+tunnel-client admin tunnels create \
+  --name "termpilot" \
+  --description "TermPilot local iTerm2 MCP" \
+  --organization-id org_...
+```
+
+You can use `--workspace-id ws_...` instead of or together with
+`--organization-id`. Copy the returned `tunnel_...` ID. Once the tunnel exists,
+TermPilot only needs that ID and a runtime API key; the admin key is no longer
+needed by the runtime.
+
+### 3. Store and load the runtime key
+
+The recommended local setup is a repository `.env` file:
+
+```dotenv
+CONTROL_PLANE_API_KEY=sk-...
+```
+
+`.env` is ignored by this repository, but neither TermPilot nor
+`tunnel-client` automatically loads it. Load it into the current shell before
+`setup`, `status`, or `doctor`:
+
+```bash
+set -a
+source .env
+set +a
+```
+
+Alternatively, export it directly:
+
+```bash
+export CONTROL_PLANE_API_KEY="sk-..."
+```
+
+TermPilot stores only the reference `env:CONTROL_PLANE_API_KEY` in the generated
+tunnel profile; it does not put the secret value into the command line or print
+it.
+
+### 4. Start the managed runtime
+
+Connect TermPilot to the existing tunnel:
+
+```bash
+uv run termpilot chatgpt setup --tunnel-id tunnel_0123456789abcdef0123456789abcdef
+```
+
+`setup` launches a long-running managed `tunnel-client` process, which in turn
+starts this checkout's `python -m termpilot.main` stdio MCP server. A healthy
+setup reports `Process running: yes`, `Healthy: yes`, and `Ready: yes`.
+
+Inspect or troubleshoot the connection with:
+
+```bash
+uv run termpilot chatgpt status
+uv run termpilot chatgpt doctor
+```
+
+After a reboot or after stopping the managed runtime, load `.env` again and run
+the same `setup --tunnel-id ...` command. The existing tunnel is reused.
+
+To stop the local runtime without deleting the remote tunnel:
+
+```bash
+uv run termpilot chatgpt disconnect
+```
+
+### 5. Add TermPilot to ChatGPT Classic
+
+After `setup` succeeds:
+
+1. Open **ChatGPT Settings → Plugins** (or
+   [ChatGPT Plugins](https://chatgpt.com/plugins)).
+2. Create a new developer-mode plugin/app, for example named `termpilot`.
+3. Under **Connection**, choose **Tunnel**, not **Server URL**.
+4. Select the tunnel or paste its `tunnel_id`.
+5. Save the plugin and allow the TermPilot tools you want ChatGPT to use.
+
+The tunnel runtime must remain running while ChatGPT discovers or calls the MCP
+tools. You do not need OAuth for the local TermPilot MCP server when using the
+Secure MCP Tunnel connection.
+
+## Frequently Asked Questions
+
+### `tunnel-client is not installed or is not available on PATH`
+
+Install the supported client and verify it is visible:
+
+```bash
+brew install openai/tools/tunnel-client
+which tunnel-client
+tunnel-client --version
+```
+
+### I put `CONTROL_PLANE_API_KEY` in `.env`, but TermPilot says it is missing
+
+Creating `.env` does not export its variables. Load it into each shell/process
+that starts or diagnoses the tunnel runtime:
+
+```bash
+set -a
+source .env
+set +a
+uv run termpilot chatgpt setup --tunnel-id tunnel_...
+```
+
+### What is the difference between `CONTROL_PLANE_API_KEY` and `OPENAI_ADMIN_KEY`?
+
+`CONTROL_PLANE_API_KEY` is the runtime key used by the long-running tunnel
+daemon. It needs **Tunnels Read + Use**. `OPENAI_ADMIN_KEY` is for administrative
+tunnel CRUD such as `tunnel-client admin tunnels create`; the TermPilot runtime
+does not need it when attaching to an existing tunnel.
+
+### Why does a manual `tunnel-client runtimes connect` complain about a missing key?
+
+The generated profile contains an environment reference such as
+`env:CONTROL_PLANE_API_KEY`. The process starting that profile must therefore
+have the variable exported. Prefer `uv run termpilot chatgpt setup ...`, which
+supplies the correct runtime-key reference and MCP command consistently.
+
+### ChatGPT sends a command, but TermPilot says `iTerm2 is not running or its Python API is disabled`
+
+First verify iTerm2 itself:
+
+1. Open **iTerm2 → Settings → General → Magic**.
+2. Enable **Python API**.
+3. Set it to **Allow all apps to connect** (or explicitly allow the process that
+   runs TermPilot).
+
+Then test the iTerm2 API directly from the TermPilot environment:
+
+```bash
+uv run python - <<'PY'
+import asyncio
+import iterm2
+
+async def main():
+    connection = await iterm2.Connection.async_create()
+    app = await iterm2.async_get_app(connection)
+    print([s.session_id for w in app.windows for t in w.tabs for s in t.sessions])
+
+asyncio.run(main())
+PY
+```
+
+If this prints session IDs, the iTerm2 API is working and the problem is in the
+TermPilot/iTerm2 boundary rather than the ChatGPT tunnel.
+
+### Why did an older TermPilot build fail even though the direct iTerm2 test worked?
+
+An earlier adapter called `iterm2.async_get_app(..., create_if_needed=False)`.
+With iTerm2 3.6.x this can return `None` even while iTerm2 is already running.
+TermPilot now allows the SDK to create its `App` wrapper, matching the working
+`iterm2.async_get_app(connection)` call.
+
+### The tunnel log says `dispatcher forwarded command to MCP server`, but ChatGPT still gets an iTerm2 error
+
+That log line proves the path **ChatGPT → Secure MCP Tunnel → TermPilot MCP** is
+working. Debug the local **TermPilot → iTerm2 Python API** boundary next instead
+of recreating the ChatGPT plugin or tunnel.
+
+### ChatGPT's plugin dialog shows `Server URL` and `Tunnel`. Which one should I use?
+
+Choose **Tunnel** and select/paste the `tunnel_id`. `Server URL` is for a
+network-reachable HTTP/SSE MCP server and is not the TermPilot setup described
+here.
+
+### `Codex detected without Tunnel MCP plugin` appears in the tunnel-client log
+
+This message is about optional Codex integration. It does not prevent the
+ChatGPT Classic developer-mode plugin from using the TermPilot tunnel.
+
+### How do I know which layer is broken?
+
+Use this order:
+
+1. `uv run termpilot chatgpt status` → runtime should be running, healthy, and ready.
+2. Tunnel log contains `dispatcher forwarded command to MCP server` → ChatGPT to
+   TermPilot transport is working.
+3. Run the direct iTerm2 Python snippet above → local iTerm2 API is working.
+4. Finally test `list_sessions` from the ChatGPT TermPilot plugin.