mirror of
https://github.com/hanzoai/dev.git
synced 2026-10-25 03:32:32 +00:00
zeekayandHanzo Dev
6cbbea2d03
Our history is just-every's with author emails rewritten, so the graphs are
disjoint and git finds no merge base. Supplied one by hand: d1f1f51a41, the
just-every commit matching our Oct-2025 fork point (22 files apart). 9618
upstream commits, 7004 files, +1.81M/-159k, 37 conflicts.
Resolution:
- Upstream code where our side was the Oct-2025 prototype of a feature they
have since reimplemented 3-5x larger (agent_runs, browser_sessions,
history_cell/{agent,browser}, the vt100 harness and its snapshots).
- Upstream's config.rs module split (builder/defaults/sources/validation)
kept; zen5-coder and the provider-follows-model rule re-applied on top.
- Ours where the file IS the identity: README, package.json, postinstall,
release notes pipeline, integration-zed.
- Hybrid where upstream improved a file we had branded: updates.rs (their
release-repo migration, our hanzoai/dev), release.yml (their fail-fast npm
auth check, our package name), chatwidget.rs (their turn handling, our
HANZO_USER_KEY hint), exec human output (their 237 lines, our banner).
Superseded and dropped deliberately: our resume_command_name() coder-alias
hack — upstream's derive_resume_command_name() reads the invocation basename
generically, which yields "dev" for us.
LLM.md now records the real topology and the sync point; AGENTS.md and
CLAUDE.md are symlinks to it again. Single parent on purpose: adopting
jecode/main as a second parent would re-import 13,742 commits carrying the
upstream author emails a prior rewrite deliberately removed.
Version 0.2.188 -> 0.2.189.
Co-authored-by: Hanzo Dev <[email protected]>
104 lines
3.7 KiB
Markdown
104 lines
3.7 KiB
Markdown
# FAQ
|
|
|
|
## Thread vs turn
|
|
|
|
- A `Thread` is conversation state.
|
|
- A `Turn` is one model execution inside that thread.
|
|
- Multi-turn chat means multiple turns on the same `Thread`.
|
|
|
|
## `run()` vs `stream()`
|
|
|
|
- `TurnHandle.run()` / `AsyncTurnHandle.run()` is the easiest path. It consumes events until completion and returns the canonical generated app-server `Turn` model.
|
|
- `TurnHandle.stream()` / `AsyncTurnHandle.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
|
|
|
|
Choose `run()` for most apps. Choose `stream()` for progress UIs, custom timeout logic, or custom parsing.
|
|
|
|
## Sync vs async clients
|
|
|
|
- `Codex` is the sync public API.
|
|
- `AsyncCodex` is an async replica of the same public API shape.
|
|
- Prefer `async with AsyncCodex()` for async code. It is the standard path for
|
|
explicit startup/shutdown, and `AsyncCodex` initializes lazily on context
|
|
entry or first awaited API use.
|
|
|
|
If your app is not already async, stay with `Codex`.
|
|
|
|
## Public kwargs are snake_case
|
|
|
|
Public API keyword names are snake_case. The SDK still maps them to wire camelCase under the hood.
|
|
|
|
If you are migrating older code, update these names:
|
|
|
|
- `approvalPolicy` -> `approval_policy`
|
|
- `baseInstructions` -> `base_instructions`
|
|
- `developerInstructions` -> `developer_instructions`
|
|
- `modelProvider` -> `model_provider`
|
|
- `modelProviders` -> `model_providers`
|
|
- `sortKey` -> `sort_key`
|
|
- `sourceKinds` -> `source_kinds`
|
|
- `outputSchema` -> `output_schema`
|
|
- `sandboxPolicy` -> `sandbox_policy`
|
|
|
|
## Why only `thread_start(...)` and `thread_resume(...)`?
|
|
|
|
The public API keeps only explicit lifecycle calls:
|
|
|
|
- `thread_start(...)` to create new threads
|
|
- `thread_resume(thread_id, ...)` to continue existing threads
|
|
|
|
This avoids duplicate ways to do the same operation and keeps behavior explicit.
|
|
|
|
## Why does constructor fail?
|
|
|
|
`Codex()` is eager: it starts transport and calls `initialize` in `__init__`.
|
|
|
|
Common causes:
|
|
|
|
- published runtime package (`openai-codex-cli-bin`) is not installed
|
|
- local `codex_bin` override points to a missing file
|
|
- local auth/session is missing
|
|
- incompatible/old app-server
|
|
|
|
Maintainers stage releases by building the SDK once and the runtime once per
|
|
platform with the same pinned runtime version. Publish `openai-codex-cli-bin`
|
|
as platform wheels only; do not publish an sdist:
|
|
|
|
```bash
|
|
cd sdk/python
|
|
python scripts/update_sdk_artifacts.py generate-types
|
|
python scripts/update_sdk_artifacts.py \
|
|
stage-sdk \
|
|
/tmp/codex-python-release/openai-codex-app-server-sdk \
|
|
--codex-version <codex-release-tag-or-pep440-version>
|
|
python scripts/update_sdk_artifacts.py \
|
|
stage-runtime \
|
|
/tmp/codex-python-release/openai-codex-cli-bin \
|
|
/path/to/codex \
|
|
--codex-version <codex-release-tag-or-pep440-version>
|
|
```
|
|
|
|
If you are packaging a binary for a different target than the Python build
|
|
host, pass `--platform-tag ...` to `stage-runtime`. The intended one-off matrix
|
|
is `macosx_11_0_arm64`, `macosx_10_9_x86_64`, `musllinux_1_1_aarch64`,
|
|
`musllinux_1_1_x86_64`, `win_arm64`, and `win_amd64`.
|
|
|
|
## Why does a turn "hang"?
|
|
|
|
A turn is complete only when `turn/completed` arrives for that turn ID.
|
|
|
|
- `run()` waits for this automatically.
|
|
- With `stream()`, keep consuming notifications until completion.
|
|
|
|
## How do I retry safely?
|
|
|
|
Use `retry_on_overload(...)` for transient overload failures (`ServerBusyError`).
|
|
|
|
Do not blindly retry all errors. For `InvalidParamsError` or `MethodNotFoundError`, fix inputs/version compatibility instead.
|
|
|
|
## Common pitfalls
|
|
|
|
- Starting a new thread for every prompt when you wanted continuity.
|
|
- Forgetting to `close()` (or not using context managers).
|
|
- Assuming `run()` returns extra SDK-only fields instead of the generated `Turn` model.
|
|
- Mixing SDK input classes with raw dicts incorrectly.
|