Skip to content

Commit 656376f

Browse files
authored
Merge pull request #1744 from lidge-jun/int/260815-old-drafts
feat: land six repaired cherry-picks (MiniMax, picker order, terminal guard, streamAborted, imageInput, droid docs)
2 parents 420db62 + b05c494 commit 656376f

84 files changed

Lines changed: 3121 additions & 91 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs-site/astro.config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ export default defineConfig({
8585
translations: { ko: "가이드", "zh-CN": "指南", "zh-TW": "指南", ru: "Руководства", ja: "ガイド", tr: "Kılavuzlar" },
8686
items: [
8787
{ label: "Providers", translations: { ko: "프로바이더", "zh-CN": "提供商", "zh-TW": "供應商", ru: "Провайдеры", ja: "プロバイダー", tr: "Sağlayıcılar" }, slug: "guides/providers" },
88+
{ label: "Factory Droid Bridge", translations: { ko: "Factory Droid 브리지" }, slug: "guides/factory-droid" },
8889
{ label: "Model Routing", translations: { ko: "모델 라우팅", "zh-CN": "模型路由", "zh-TW": "模型路由", ru: "Маршрутизация моделей", ja: "モデルルーティング", tr: "Model Yönlendirme" }, slug: "guides/model-routing" },
8990
{ label: "Codex Integration", translations: { ko: "Codex 통합", "zh-CN": "Codex 集成", "zh-TW": "Codex 整合", ru: "Интеграция с Codex", ja: "Codex 連携", tr: "Codex Entegrasyonu" }, slug: "guides/codex-integration" },
9091
{ label: "Codex App Model Picker", translations: { ko: "Codex App 모델 선택기", "zh-CN": "Codex App 模型选择器", "zh-TW": "Codex App 模型選擇器", ru: "Выбор модели в Codex App", ja: "Codex App モデルピッカー", tr: "Codex App Model Seçici" }, slug: "guides/codex-app-models" },
@@ -95,6 +96,7 @@ export default defineConfig({
9596
{ label: "opencode", translations: { ko: "opencode", "zh-CN": "opencode", "zh-TW": "opencode", ru: "opencode", ja: "opencode", tr: "opencode" }, slug: "guides/opencode" },
9697
{ label: "Pi", translations: { ko: "Pi", "zh-CN": "Pi", "zh-TW": "Pi", ru: "Pi", ja: "Pi", tr: "Pi" }, slug: "guides/pi" },
9798
{ label: "Integrations", translations: { ko: "연동", "zh-CN": "集成", "zh-TW": "整合", ru: "Интеграции", ja: "連携", tr: "Entegrasyonlar" }, slug: "guides/integrations" },
99+
{ label: "MiniMax clients", translations: { ko: "MiniMax 클라이언트", "zh-CN": "MiniMax 客户端", "zh-TW": "MiniMax 客戶端", ru: "Клиенты MiniMax", ja: "MiniMax クライアント", tr: "MiniMax İstemcileri" }, slug: "guides/minimax" },
98100
{ label: "Sidecars: Web Search & Vision", translations: { ko: "사이드카: 웹 검색 & 비전", "zh-CN": "边车:网络搜索与视觉", "zh-TW": "邊車:網路搜尋與視覺", ru: "Сайдкары: веб-поиск и зрение", ja: "サイドカー: ウェブ検索 & ビジョン", tr: "Sidecar'lar: Web Arama ve Görme" }, slug: "guides/sidecars" },
99101
{ label: "Image Bridge", translations: { ko: "이미지 브릿지", "zh-CN": "图像桥接", "zh-TW": "圖像橋接", ru: "Image Bridge", ja: "画像ブリッジ", tr: "Image Bridge" }, slug: "guides/image-bridge" },
100102
{ label: "Video Bridge", translations: { ko: "비디오 브릿지", "zh-CN": "视频桥接", "zh-TW": "影片橋接", ru: "Video Bridge", ja: "動画ブリッジ", tr: "Video Bridge" }, slug: "guides/video-bridge" },
62.7 KB
Loading

‎docs-site/src/content/docs/guides/combos.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,14 @@ default and leaves the target's own behavior unchanged. Supported values are `lo
211211
`high`, `xhigh`, `max`, and `ultra`; omit the field or set it to `null` to leave effort entirely to
212212
the caller and target.
213213

214+
## Image / multimodal capability
215+
216+
By default a combo publishes the **intersection** of its targets' input modalities (image is
217+
enabled only when every target advertises it). Set `imageInput: "disabled"` to force text-only
218+
even when every target supports images — the catalog drops `image` from `inputModalities`, and
219+
image-bearing requests are rejected with HTTP 400 before any target is called. `"auto"` (or
220+
omitting the field) keeps the automatic intersection.
221+
214222
## Encrypted v2 sub-agent tasks
215223

216224
There is one important limitation for Codex v2 sub-agents ([issue #92](https://github.com/lidge-jun/opencodex/issues/92)).
@@ -304,6 +312,7 @@ Combos are stored in the top-level `combos` object, keyed by combo id:
304312
| `strategy` | No | `"failover"` | `"failover"` or `"round-robin"`. |
305313
| `stickyLimit` | No | `1` | Integer from 1 to 100 successful requests per round-robin selection. |
306314
| `defaultEffort` | No | `null` | `low`, `medium`, `high`, `xhigh`, `max`, or `ultra`; applied only when the caller omits effort and the target advertises support. |
315+
| `imageInput` | No | `"auto"` | `"auto"` or `"disabled"`. `"auto"` publishes image support only when every target supports images; `"disabled"` forces text-only (drops image from published modalities and rejects image-bearing requests before dispatch). |
307316
| `alias` | No | none | Optional trimmed public model id; use the alias rules above. An empty value is stored as no alias. |
308317
| `nativeAlias` | No | `false` | Explicitly permit a currently supported bare native `alias` to take routing and catalog precedence. Never inferred from the alias. |
309318
| `displayName` | No | none | Bounded display-only catalog label. Required and non-empty when `nativeAlias` is true. |
Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: Factory Droid bridge
3+
description: Connect Factory Droid models to opencodex through a local Responses-compatible bridge.
4+
---
5+
6+
Factory Droid is an agent runtime, not a documented OpenAI-compatible inference endpoint. If a
7+
custom provider pointed at an internal Factory LLM URL returns `403 Forbidden`, changing only the
8+
opencodex adapter or adding provider headers does not make that private route a supported public API.
9+
10+
The working integration is:
11+
12+
```text
13+
Text-only Responses client
14+
-> opencodex (http://127.0.0.1:10100/v1/responses)
15+
-> local Responses bridge (http://127.0.0.1:11435/v1/responses)
16+
-> official droid exec command
17+
-> Factory account and selected model
18+
```
19+
20+
This keeps the Factory credential inside the official Droid client. OpenCodex receives a separate,
21+
local-only bridge token.
22+
23+
## What failed and why
24+
25+
| Symptom | Cause | Fix |
26+
| --- | --- | --- |
27+
| `403 Forbidden` from a Factory LLM URL | The URL is not a documented general-purpose OpenAI endpoint for third-party clients | Invoke Factory through the official Droid CLI or SDK |
28+
| `404` at `/models/models` | The provider base URL already ended in `/models` | Use an API root as `baseUrl`; never include the discovery path |
29+
| Model search fails | The bridge does not expose a complete live catalog | Set `liveModels: false` and provide a static `models` list |
30+
| Loopback provider is rejected | Private-network access is denied by default | Set `allowPrivateNetwork: true` only for the loopback bridge |
31+
| `${DROID_BRIDGE_TOKEN}` is unresolved | The variable is missing from the opencodex service environment | Inject it into the service process, not only an interactive shell |
32+
| `OutputTextDelta without active item` | The bridge emitted a text delta before opening an output item and content part | Emit the complete Responses SSE lifecycle in order |
33+
34+
The same Factory credential can therefore work in `droid exec` while a direct request to an
35+
undocumented LLM URL still returns `403`. Those results test different products and should not be
36+
treated as contradictory.
37+
38+
## Prerequisites
39+
40+
1. Install and sign in to the [Droid CLI](https://docs.factory.ai/droid-cli/quickstart).
41+
2. Confirm a bounded headless request works:
42+
43+
```bash
44+
droid exec --model glm-5.2 --output-format json "Reply with DROID_OK only."
45+
```
46+
47+
3. Run a local bridge that invokes `droid exec` (or the official Droid SDK) and exposes:
48+
49+
- `GET /healthz`
50+
- `GET /v1/models`
51+
- `POST /v1/responses`
52+
53+
Factory documents `droid exec` as its non-interactive automation surface and recommends JSON output
54+
for scripts. For a longer-lived integration, Factory also documents stream JSON-RPC and official
55+
TypeScript and Python SDKs in the
56+
[Droid Exec guide](https://docs.factory.ai/droid-exec/overview).
57+
58+
## Bridge contract
59+
60+
Bind the bridge to `127.0.0.1`, require a randomly generated bearer token, cap request sizes, and
61+
allowlist model IDs. The minimal bridge accepts only these Responses `input` shapes:
62+
63+
- a non-empty string; or
64+
- an array containing only `message` items. Each message must have a `user`, `developer`, `system`,
65+
or `assistant` role and either string content or text-only content parts (`input_text` for input
66+
roles and `output_text` for assistant history).
67+
68+
Validate the complete request before invoking Droid. If an input part is an image or file, `tools`
69+
contains any tool definition, or `input` contains a tool call or result (`function_call`,
70+
`function_call_output`, `custom_tool_call`, or `custom_tool_call_output`), return HTTP `400` with a
71+
Responses-style `invalid_request_error`. Use a stable bridge-specific code such as
72+
`unsupported_bridge_input` and identify the rejected field in the message. Do this before starting
73+
SSE, even when `stream: true`; never discard, stringify, or flatten unsupported content into the
74+
prompt.
75+
76+
```json
77+
{
78+
"error": {
79+
"type": "invalid_request_error",
80+
"code": "unsupported_bridge_input",
81+
"param": "tools",
82+
"message": "The minimal Droid bridge does not accept tool definitions."
83+
}
84+
}
85+
```
86+
87+
For an accepted request, the bridge should:
88+
89+
1. Convert the accepted Responses `input` to a prompt.
90+
2. invoke `droid exec --model <id> --output-format json <prompt>`;
91+
3. parse the final `result` and `session_id`;
92+
4. return an OpenAI Responses envelope; and
93+
5. map `previous_response_id` to the Droid session ID when continuation is required.
94+
95+
For streaming responses, emit this lifecycle in order:
96+
97+
```text
98+
response.created
99+
response.output_item.added
100+
response.content_part.added
101+
response.output_text.delta
102+
response.output_text.done
103+
response.content_part.done
104+
response.output_item.done
105+
response.completed
106+
```
107+
108+
Do not expose the bridge on `0.0.0.0` and do not reuse the Factory credential as the bridge bearer
109+
token.
110+
111+
## OpenCodex provider configuration
112+
113+
Create the custom provider with the explicit provider ID `droid`:
114+
115+
```bash
116+
ocx provider add droid \
117+
--adapter openai-responses \
118+
--base-url http://127.0.0.1:11435/v1 \
119+
--default-model glm-5.2 \
120+
--allow-private-network
121+
```
122+
123+
This creates the `providers.droid` config entry. In the dashboard, open **Providers → droid → Edit
124+
JSON** and replace that provider's value with:
125+
126+
```json
127+
{
128+
"adapter": "openai-responses",
129+
"baseUrl": "http://127.0.0.1:11435/v1",
130+
"responsesPath": "/responses",
131+
"allowPrivateNetwork": true,
132+
"authMode": "key",
133+
"apiKey": "${DROID_BRIDGE_TOKEN}",
134+
"liveModels": false,
135+
"models": ["glm-5.2", "glm-5.2-fast", "kimi-k3"],
136+
"defaultModel": "glm-5.2"
137+
}
138+
```
139+
140+
The model IDs are examples. Keep only models that `droid exec` can use for the signed-in Factory
141+
account. Do not add Factory-specific inference headers to this provider: its upstream is the local
142+
bridge, not a Factory HTTP endpoint.
143+
144+
After saving a provider or changing its static catalog, synchronize and restart the Codex
145+
app-server so new sessions read the updated catalog:
146+
147+
```bash
148+
ocx sync --restart-codex
149+
ocx doctor
150+
```
151+
152+
Restarting Codex app-server processes interrupts active Codex work. Run the restart only after
153+
finishing or saving those sessions.
154+
155+
## Verify the complete route
156+
157+
Check each boundary separately:
158+
159+
```bash
160+
curl -fsS http://127.0.0.1:11435/healthz
161+
ocx doctor
162+
ocx access test droid/glm-5.2 --protocol responses
163+
```
164+
165+
A provider row or model-picker entry proves only catalog visibility. The integration is working only
166+
after the Responses probe returns through the `droid/<model>` route.
167+
168+
## Current limitation
169+
170+
The minimal bridge above translates text and the Responses SSE lifecycle. It does **not** implement
171+
the full bidirectional Codex function/tool-call protocol. Codex App and `codex exec` normally send
172+
tool definitions even when a prompt says not to call tools, and the current Codex CLI has no general
173+
flag that removes those definitions. The minimal bridge must reject those requests with the `400`
174+
contract above. Tool definitions, tool calls, tool results, permissions, cancellation, and rich
175+
Droid events require a stateful bridge built on Factory's stream JSON-RPC mode or an official Droid
176+
SDK. Treat `ocx access test` success as text-path verification, not Codex agent or tool-path
177+
verification.

‎docs-site/src/content/docs/guides/integrations.md‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
22
title: Integrations
3-
description: Connect opencodex to OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code and DeepSeek Harness from the dashboard — one switch per client, with a backup taken before every write.
3+
description: Connect opencodex to OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness and MiniMax Code from the dashboard — one switch per client, with a backup taken before every write.
44
---
55

66
The **Integrations** tab writes opencodex's provider block into a client's own config
7-
file, and removes it again. Eight clients work this way, each with a switch:
7+
file, and removes it again. Nine clients work this way, each with a switch:
88

99
| Client | Config file | Format | When the change takes effect | Credential |
1010
|---|---|---|---|---|
@@ -16,13 +16,20 @@ file, and removes it again. Eight clients work this way, each with a switch:
1616
| Kimi Code | `~/.kimi-code/config.toml` | TOML | on restart, or `/reload` | loopback placeholder |
1717
| Gajae Code | `~/.gjc/agent/models.yml` | YAML | new sessions, or when you open `/model` |`OPENCODEX_GAJAE_API_KEY` |
1818
| DeepSeek Harness (DSH) | `$DSH_HOME/settings.yaml` (default `~/.dsh/settings.yaml`) | YAML | hot reload | non-secret loopback bearer placeholder |
19+
| MiniMax Code | `~/.minimax/config.yaml` | YAML | new sessions, or after opening the model picker | loopback placeholder |
1920

2021
Managed DSH support has a compatibility floor of **DSH 0.1.0-rc.6**. OpenCodex owns only
2122
`llm-pi-ai.providers.opencodex`; Apply and Refresh replace that fragment, Disable removes only that
2223
fragment, and Restore puts back a recorded snapshot. DSH hot reloads provider changes. These
2324
operations do not change the user's default model or the native `deepseek-official` provider.
2425
The managed DSH integration is currently loopback-only and never writes a real credential.
2526

27+
MiniMax Code follows `MINIMAX_DATA_DIR`, then `MAVIS_DATA_DIR`, before falling
28+
back to `~/.minimax`. Its managed block owns only `custom_provider.opencodex`.
29+
It does not change `defaultModel`, the selected MiniMax credential source, or
30+
the user's MiniMax login. Choose a `custom_provider:opencodex/<provider/model>`
31+
entry in MCode after connecting it.
32+
2633
Paths honor each client's own environment override where it has one. For OMP,
2734
`OMP_PROFILE` wins over `PI_PROFILE` by presence, even when explicitly empty. A named profile
2835
uses `PI_CONFIG_DIR` as a directory name relative to the user's home and ignores `PI_CODING_AGENT_DIR`; without a named profile,
@@ -83,8 +90,8 @@ than 1000 levels — which locks the switch instead, so nothing is silently chan
8390
**OMP** is unaffected by sibling edits too, for a different reason: its writer
8491
patches only its own `providers.opencodex` range byte-wise, so the rest of the
8592
file is never rewritten. For the remaining formats that can carry comments
86-
(Hermes, OpenClaw, Kimi Code, Gajae Code — YAML, JSON5 and TOML written as whole
87-
documents), or
93+
(Hermes, OpenClaw, Kimi Code, Gajae Code, MiniMax Code — YAML, JSON5 and TOML
94+
written as whole documents), or
8895
whenever our own entries were edited, the switch locks and disable refuses rather
8996
than guessing which edits were yours.
9097

@@ -106,8 +113,8 @@ changed value and calling it success. You will see the file named and nothing on
106113
disk will have moved. Editing that file by hand still works; it is only our
107114
automatic rewrite that declines.
108115

109-
**Pi, Kimi Code, Gajae Code and the managed DSH integration only work against a loopback bind.**
110-
The first three have no config field for the `x-opencodex-api-key` header a non-loopback bind
116+
**Pi, Kimi Code, Gajae Code, MiniMax Code and the managed DSH integration only work against a loopback bind.**
117+
The first four have no config field for the `x-opencodex-api-key` header a non-loopback bind
111118
requires. DSH has a generic headers map, but rc.6 does not document that dedicated admission
112119
header as a supported integration contract, so the managed writer fails closed instead of
113120
guessing. Give them loopback access through an SSH tunnel or a local forwarder that adds the header.
@@ -138,6 +145,29 @@ ocx integration client history --client hermes
138145
ocx integration client restore --op <opId> [--confirm-drift]
139146
```
140147

148+
For MiniMax Code, connect the provider once and launch through the checked wrapper:
149+
150+
```bash
151+
ocx integration client enable --client mcode
152+
ocx mcode
153+
```
154+
155+
The separate MiniMax platform CLI (`mmx`) is not a file-toggle integration. Its text
156+
commands use MiniMax's Anthropic-compatible endpoint, so OpenCodex provides a
157+
credential-isolated, loopback-only launcher:
158+
159+
```bash
160+
ocx mmx text chat --model anthropic/claude-opus-5 --message "Hello"
161+
ocx mmx text repl --model openai/gpt-5.6-sol
162+
```
163+
164+
Only `mmx text chat` and `mmx text repl` are proxied. Run plain `mmx` for
165+
MiniMax-native image, video, speech, music, vision, search, quota, auth, config, file
166+
and update commands. The wrapper uses a temporary config containing only a non-secret
167+
loopback placeholder; it never loads your `~/.mmx` OAuth or API-key credentials, and
168+
it refuses `--api-key`, `--base-url` and `--region` overrides. See
169+
[MiniMax clients](/guides/minimax/) for the complete workflow and limits.
170+
141171
`--confirm-drift` is never assumed. If the file changed after the operation you are
142172
restoring, the command refuses and tells you, because replacing your newer edits is your
143173
decision to make.

0 commit comments

Comments
 (0)