mirror of https://github.com/hanzoai/dev.git synced 2026-10-25 03:32:32 +00:00

Files

T

zeekayandHanzo Dev 6cbbea2d03 merge: just-every/code v0.6.169 (e4fe007150) — keep Hanzo identity

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]>

2026-08-05 23:09:12 -07:00

3.7 KiB

Raw Permalink Blame History

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:

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.

3.7 KiB Raw Permalink Blame History

FAQ