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]>
111 lines
3.2 KiB
Markdown
111 lines
3.2 KiB
Markdown
# Getting Started
|
|
|
|
This is the fastest path from install to a multi-turn thread using the public SDK surface.
|
|
|
|
The SDK is experimental. Treat the API, bundled runtime strategy, and packaging details as unstable until the first public release.
|
|
|
|
## 1) Install
|
|
|
|
From repo root:
|
|
|
|
```bash
|
|
cd sdk/python
|
|
uv sync
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
Requirements:
|
|
|
|
- Python `>=3.10`
|
|
- uv
|
|
- installed `openai-codex-cli-bin` runtime package, or an explicit `codex_bin` override
|
|
- local Codex auth/session configured
|
|
|
|
## 2) Run your first turn (sync)
|
|
|
|
```python
|
|
from codex_app_server import Codex
|
|
|
|
with Codex() as codex:
|
|
server = codex.metadata.serverInfo
|
|
print("Server:", None if server is None else server.name, None if server is None else server.version)
|
|
|
|
thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
|
|
result = thread.run("Say hello in one sentence.")
|
|
|
|
print("Thread:", thread.id)
|
|
print("Text:", result.final_response)
|
|
print("Items:", len(result.items))
|
|
```
|
|
|
|
What happened:
|
|
|
|
- `Codex()` started and initialized `codex app-server`.
|
|
- `thread_start(...)` created a thread.
|
|
- `thread.run("...")` started a turn, consumed events until completion, and returned the final assistant response plus collected items and usage.
|
|
- `result.final_response` is `None` when no final-answer or phase-less assistant message item completes for the turn.
|
|
- use `thread.turn(...)` when you need a `TurnHandle` for streaming, steering, interrupting, or turn IDs/status
|
|
- one client can have only one active turn consumer (`thread.run(...)`, `TurnHandle.stream()`, or `TurnHandle.run()`) at a time in the current experimental build
|
|
|
|
## 3) Continue the same thread (multi-turn)
|
|
|
|
```python
|
|
from codex_app_server import Codex
|
|
|
|
with Codex() as codex:
|
|
thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
|
|
|
|
first = thread.run("Summarize Rust ownership in 2 bullets.")
|
|
second = thread.run("Now explain it to a Python developer.")
|
|
|
|
print("first:", first.final_response)
|
|
print("second:", second.final_response)
|
|
```
|
|
|
|
## 4) Async parity
|
|
|
|
Use `async with AsyncCodex()` as the normal async entrypoint. `AsyncCodex`
|
|
initializes lazily, and context entry makes startup/shutdown explicit.
|
|
|
|
```python
|
|
import asyncio
|
|
from codex_app_server import AsyncCodex
|
|
|
|
|
|
async def main() -> None:
|
|
async with AsyncCodex() as codex:
|
|
thread = await codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
|
|
result = await thread.run("Continue where we left off.")
|
|
print(result.final_response)
|
|
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## 5) Resume an existing thread
|
|
|
|
```python
|
|
from codex_app_server import Codex
|
|
|
|
THREAD_ID = "thr_123" # replace with a real id
|
|
|
|
with Codex() as codex:
|
|
thread = codex.thread_resume(THREAD_ID)
|
|
result = thread.run("Continue where we left off.")
|
|
print(result.final_response)
|
|
```
|
|
|
|
## 6) Generated models
|
|
|
|
The convenience wrappers live at the package root, but the canonical app-server models live under:
|
|
|
|
```python
|
|
from codex_app_server.generated.v2_all import Turn, TurnStatus, ThreadReadResponse
|
|
```
|
|
|
|
## 7) Next stops
|
|
|
|
- API surface and signatures: `docs/api-reference.md`
|
|
- Common decisions/pitfalls: `docs/faq.md`
|
|
- End-to-end runnable examples: `examples/README.md`
|