162 lines
6.2 KiB
Markdown
162 lines
6.2 KiB
Markdown
# Known Issues
|
|
|
|
This document tracks unresolved issues that are known to cause failures or unexpected behavior in the gemini-cli workspace template. Entries are organized by severity and include workaround instructions where available.
|
|
|
|
---
|
|
|
|
## Issue 1: Missing `GEMINI_API_KEY` causes silent startup failure
|
|
|
|
**Severity:** High
|
|
|
|
**Description:**
|
|
|
|
If `GEMINI_API_KEY` is unset when the container starts, gemini-cli initializes without an API key but does not exit immediately. The agent starts, accepts sessions, and then produces no response for every prompt — the platform sees an agent that "never replies."
|
|
|
|
The underlying cause is that gemini-cli's auth layer attempts to load the key lazily on the first API call, not at startup. No error is raised until the first `stream_response()` call, which then fails with a generic timeout or an auth error that may be swallowed by the platform shim.
|
|
|
|
**Affected versions:** All template versions prior to the env-validation shim in `adapter.py` (see workaround).
|
|
|
|
**Workaround:**
|
|
|
|
Validate the env var before invoking the adapter:
|
|
|
|
```bash
|
|
if [ -z "$GEMINI_API_KEY" ]; then
|
|
echo "ERROR: GEMINI_API_KEY is not set" >&2
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
Or add an early check in `adapter.py`:
|
|
|
|
```python
|
|
import os
|
|
def connect(platform_url, workspace_id, timeout=30):
|
|
if not os.environ.get("GEMINI_API_KEY"):
|
|
raise RuntimeError("GEMINI_API_KEY environment variable is not set")
|
|
...
|
|
```
|
|
|
|
**Tracking:** Internal issue `WKS-001`.
|
|
|
|
---
|
|
|
|
## Issue 2: `system-prompt.md` injected after gemini-cli defaults, overriding template's SOUL.md conventions
|
|
|
|
**Severity:** Medium
|
|
|
|
**Description:**
|
|
|
|
gemini-cli loads system prompts in the following order:
|
|
|
|
1. Built-in defaults (`gemini-cli/resources/defaults/system.txt`)
|
|
2. `SOUL.md` in the current working directory (gemini-cli's convention for agent personality files)
|
|
3. `system-prompt.md` injected by the workspace template
|
|
|
|
Because `system-prompt.md` is concatenated last, it overwrites any setting that was already set in `SOUL.md` (or gemini-cli's defaults). This means template authors cannot rely on gemini-cli's `SOUL.md` convention to set agent personality, guardrails, or tool restrictions — anything set there is silently clobbered.
|
|
|
|
This is particularly problematic for deployments that rely on gemini-cli's default tool list (which includes shell execution, file read/write, and internet access) since the template's `system-prompt.md` must explicitly deny those tools to enforce a tighter scope.
|
|
|
|
**Workaround:**
|
|
|
|
Do not use `SOUL.md` for runtime configuration. Put all system-prompt content exclusively in `system-prompt.md` and leave `SOUL.md` absent or empty. The adapter startup script should delete or truncate `SOUL.md` if present:
|
|
|
|
```bash
|
|
# In Dockerfile, after COPY:
|
|
RUN rm -f /workspace/SOUL.md
|
|
```
|
|
|
|
**Tracking:** Internal issue `WKS-002`.
|
|
|
|
---
|
|
|
|
## Issue 3: `config.yaml` model override not propagated to the gemini-cli config file inside Docker
|
|
|
|
**Severity:** Medium
|
|
|
|
**Description:**
|
|
|
|
The template's `config.yaml` exposes `runtime.model` as the canonical model selection knob. However, gemini-cli reads its own config file (`~/.config/gemini-cli/config.json`) for model selection, not `config.yaml`. The template's `config.yaml` is read by the adapter shim only; it does not rewrite gemini-cli's config file.
|
|
|
|
As a result, even if `config.yaml` specifies `model: gemini-2.5-pro`, the container may still run the model configured in gemini-cli's internal config (defaulting to `gemini-2.0-flash`).
|
|
|
|
**Reproduction:**
|
|
|
|
```bash
|
|
# Set a non-default model in config.yaml
|
|
sed -i 's/^ model:.*/ model: gemini-2.5-pro/' config.yaml
|
|
docker build -t molecule-gemini-cli:dev .
|
|
docker run --rm molecule-gemini-cli:dev \
|
|
python -c "from adapter import stream_response; print(stream_response('s', 'what model are you'))"
|
|
# Output: "gemini-2.0-flash" (not gemini-2.5-pro)
|
|
```
|
|
|
|
**Workaround:**
|
|
|
|
The adapter must sync the model value into gemini-cli's config file before starting the session:
|
|
|
|
```python
|
|
import json, os, pathlib
|
|
|
|
def sync_model_to_gemini_config(model: str):
|
|
config_path = pathlib.Path(os.path.expanduser("~/.config/gemini-cli/config.json"))
|
|
config_path.parent.mkdir(parents=True, exist_ok=True)
|
|
if config_path.exists():
|
|
cfg = json.loads(config_path.read_text())
|
|
else:
|
|
cfg = {}
|
|
cfg["model"] = model
|
|
config_path.write_text(json.dumps(cfg, indent=2))
|
|
```
|
|
|
|
Call `sync_model_to_gemini_config()` inside `connect()` before instantiating the gemini-cli client.
|
|
|
|
**Tracking:** Internal issue `WKS-003`.
|
|
|
|
---
|
|
|
|
## Issue 4: Template schema version 1 but platform v2 introduces breaking config key renames
|
|
|
|
**Severity:** High (breaking for platform v2 deployments)
|
|
|
|
**Description:**
|
|
|
|
The template ships with `schema_version: "1"` in `config.yaml`. Platform version 2 (v2) renamed several top-level keys:
|
|
|
|
| v1 key | v2 key |
|
|
|---------------------------|----------------------------------|
|
|
| `runtime.agent` | `agent.runtime` |
|
|
| `runtime.model` | `agent.model` |
|
|
| `runtime.api_key_env` | `auth.gemini_api_key_env` |
|
|
| `adapter.platform_url` | `platform.endpoint` |
|
|
| `adapter.workspace_id_env`| `platform.workspace_id_env` |
|
|
| `adapter.timeout_seconds` | `platform.request_timeout_secs` |
|
|
|
|
Templates using v1 syntax on a v2 platform silently ignore renamed keys — the adapter gets default values instead of configured ones, leading to runtime failures that are difficult to diagnose.
|
|
|
|
**Detection:**
|
|
|
|
```bash
|
|
# Check which schema version the platform expects
|
|
curl -s https://platform.molecule.ai/api/schema-version | jq .
|
|
```
|
|
|
|
If the platform returns `2` and `config.yaml` has `schema_version: "1"`, the config is incompatible.
|
|
|
|
**Workaround:**
|
|
|
|
Maintain separate `config.v1.yaml` and `config.v2.yaml` files and select the correct one at container startup based on the platform's reported schema version:
|
|
|
|
```bash
|
|
# In Dockerfile CMD or entrypoint script:
|
|
PLATFORM_SCHEMA=$(curl -s https://platform.molecule.ai/api/schema-version | jq -r '.version')
|
|
if [ "$PLATFORM_SCHEMA" = "2" ]; then
|
|
cp /workspace/config.v2.yaml /workspace/config.yaml
|
|
else
|
|
cp /workspace/config.v1.yaml /workspace/config.yaml
|
|
fi
|
|
exec python -m adapter
|
|
```
|
|
|
|
**Tracking:** Internal issue `WKS-004`. Fixed in template v2.0 (pending release).
|