smashimo/oh-my-pi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(coding-agent): updated documentation

Browse Source 
- Updated documentation to reflect product name change from 'pi' to 'omp' throughout guides and API references.
- Restructured extension and hook documentation to clarify discovery mechanisms, loading behavior, and configuration across multiple config systems (.omp, .pi, .claude, .codex).
- Updated SDK API documentation with new method signatures: discoverHooks() -> discoverExtensions(), SessionManager methods now async, settings format changed to YAML.
- Expanded session architecture documentation with new entry types (TtsrInjectionEntry, SessionInitEntry), updated field names (fromHook -> fromExtension), and clarified session file format versioning.
- Simplified session-tree-plan.md from detailed implementation checklist to architecture summary, removing completed tasks and rollout details.
This commit is contained in:
can1357
2026-02-05 00:54:32 +01:00
parent 1949a09187
commit 7d60a1af85
18 changed files with 1846 additions and 2451 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/coding-agent/docs/python-repl.md
+40 -14
View File
@@ -12,14 +12,16 @@ python -m pip install jupyter_kernel_gateway ipykernel
## How It Works
The Python tool starts a Jupyter Kernel Gateway process locally, which manages an IPython kernel. All code execution goes through the gateway's REST and WebSocket APIs.
The Python tool uses a Jupyter Kernel Gateway and talks to it over REST and WebSocket APIs.
By default it uses a shared local gateway so multiple pi instances reuse the same gateway process.
Startup flow:
1. Spawn `python -m kernel_gateway` on a random available port
2. Wait for gateway to become ready (`GET /api/kernelspecs`)
3. Create a kernel (`POST /api/kernels`)
4. Connect WebSocket for execution messages
5. Run prelude code (helper functions)
Shared-gateway startup flow:
1. Filter the environment and resolve the Python runtime (including venv detection)
2. Acquire the shared gateway (reuse a healthy gateway or spawn `python -m kernel_gateway` on 127.0.0.1:PORT)
3. Wait for gateway readiness (`GET /api/kernelspecs`)
4. Create a kernel (`POST /api/kernels`)
5. Connect WebSocket for execution messages
6. Initialize kernel environment, run prelude helpers, and load extension modules
## External Gateway Support
@@ -47,31 +49,55 @@ This is useful for:
## Environment Propagation
- The kernel inherits a filtered environment (explicit allowlist + denylist)
- `PYTHONPATH` includes the working directory and any existing `PYTHONPATH` value
- Allowlisted prefixes include `LC_`, `XDG_`, and `OMP_`; known API-key vars are removed
- `PYTHONPATH` is passed through if present
- Virtual environments are detected via `VIRTUAL_ENV`, `.venv/`, or `venv/` and preferred when present
## Prelude Extensions
Optional `.py` modules are loaded after the prelude from:
- `~/.omp/agent/modules` and `~/.pi/agent/modules`
- `<project>/.omp/modules` and `<project>/.pi/modules`
Project modules override user modules with the same filename.
## Kernel Modes
Settings under `python` control exposure and reuse:
- `toolMode`: `ipy-only` (default), `bash-only`, `both`
- `kernelMode`: `session` (default, queued), `per-call`
- `toolMode`: `both` (default), `ipy-only`, `bash-only`
- `kernelMode`: `session` (default) or `per-call`
- `sharedGateway`: `true` (default). Setting to `false` throws an error because local (per-process) gateways are not supported; the shared gateway is required.
## Shell Bridge
Mode behavior:
- `session`: reuse kernels per session id, serialize execution, evict after 5 minutes of idle time (max 4 sessions)
- `per-call`: create a fresh kernel per tool call and shut it down afterward
The Python prelude exposes `bash()` which:
- Sources the shell snapshot when `OMP_SHELL_SNAPSHOT` is set
- Runs via `bash -lc` when available, with OS fallbacks
Environment override:
- `OMP_PY=0|bash` → `bash-only`
- `OMP_PY=1|py` → `ipy-only`
- `OMP_PY=mix|both` → `both`
## Shell Helper
The Python prelude exposes `run()` which executes a shell command via `bash -c` (or `sh -c` fallback)
and returns a `ShellResult` with `stdout`, `stderr`, and `code`.
## Output Handling
- Streams `stdout`/`stderr` as text
- `application/x-omp-status` emits structured status events for the TUI
- `image/png` display data renders inline in TUI
- `application/json` display data renders as a collapsible tree
- `text/markdown` is rendered as-is, `text/plain` is used as a fallback
- `text/html` display data is converted to basic markdown
## Troubleshooting
- **Kernel unavailable**: Ensure `python` + `jupyter-kernel-gateway` + `ipykernel` are installed; the session will fall back to bash-only.
- **Python mode override**: Check `python.toolMode` or `OMP_PY` if the Python tool is missing.
- **Shared gateway disabled**: `python.sharedGateway=false` causes the Python tool to error because local (per-process) gateways are not supported.
- **Skip preflight checks**: Set `OMP_PYTHON_SKIP_CHECK=1` to bypass kernel availability checks.
- **External gateway unreachable**: Check the URL is correct and the gateway is running. If auth is required, set `OMP_PYTHON_GATEWAY_TOKEN`.
- **IPC tracing**: Set `OMP_PYTHON_IPC_TRACE=1` to log kernel message flow.
- **Stdin requests**: Interactive input is not supported; refactor code to avoid `input()` or provide data programmatically.