codex-local-sdk-python 0.1.0__py3-none-any.whl

codex_sdk_python/data/skills/codex-local-sdk-usage/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: codex-local-sdk-usage
+description: Use when Codex needs to write, wire, or troubleshoot Python code that consumes this repository's `codex_local_sdk` package (not modify SDK internals). Trigger for requests to call `CodexLocalClient`, run or resume threads, stream JSON events, configure retries and timeouts, use schema-constrained output, or persist named sessions.
+---
+
+# Codex Local SDK Usage
+
+## Route Quickly
+Load only the reference file needed for the task:
+
+- Select an execution path: `references/task-routing.md`
+- Check methods, request flags, and result fields: `references/sdk-api-cheatsheet.md`
+- Debug failures, retries, and session issues: `references/guardrails-and-failure-modes.md`
+
+## Execute Workflow
+1. Run `scripts/preflight_check.py` to verify Python, package import, and `codex` CLI presence.
+2. Run `scripts/scaffold_usage_template.py --list` and choose the closest template.
+3. Run the scaffold command with `--template` and `--output`.
+4. Replace placeholders (`prompt`, schema, paths, session names, retries) and keep signatures aligned with the API cheat sheet.
+5. Run the generated script and inspect `CodexExecResult` (`return_code`, `turn_status`, `stderr`, `final_message`).
+6. If execution fails, apply the guardrails reference and retry.
+
+## Use Bundled Scripts
+- `scripts/preflight_check.py`: print readiness checks with optional strict mode.
+- `scripts/scaffold_usage_template.py`: copy a starter script from `assets/`.
+
+## Use Bundled Templates
+- `assets/template_sync_run.py`
+- `assets/template_live_stream.py`
+- `assets/template_thread_session.py`
+- `assets/template_resume_named_session.py`
+- `assets/template_async_run.py`
+- `assets/template_schema_output.py`
+- `assets/template_telemetry_and_retry.py`
+
+## Keep Consumer Guardrails
+- Set `timeout_seconds` for `run*` and `resume*` unless intentionally unbounded.
+- Set `json_output=True` whenever you need structured events, `thread_id`, or `turn_status`.
+- Catch `CodexExecFailedError` when `raise_on_error=True`; inspect `exc.result`.
+- Pass `session_id` or `session_name`, never both.
+- Treat live methods (`run_live*`, `resume_live*`) as startup-retry only; once a handle is returned, caller code owns interruption/retry logic.

codex_sdk_python/data/skills/codex-local-sdk-usage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Local SDK Usage"
+  short_description: "Build scripts that consume Codex Local SDK APIs"
+  default_prompt: "Use $codex-local-sdk-usage to build or troubleshoot code that uses codex_local_sdk APIs."

codex_sdk_python/data/skills/codex-local-sdk-usage/assets/template_async_run.py

@@ -0,0 +1,36 @@
+"""Template: async run and async live streaming."""
+
+import asyncio
+
+from codex_local_sdk import CodexExecRequest, CodexLocalClient, SandboxMode
+
+
+async def main() -> None:
+    client = CodexLocalClient()
+
+    result = await client.run_async(
+        CodexExecRequest(
+            prompt="TODO: replace with your prompt",
+            sandbox=SandboxMode.READ_ONLY,
+        ),
+        timeout_seconds=120,
+    )
+    print("async return_code:", result.return_code)
+    print("async final_message:\n", result.final_message)
+
+    live = await client.run_live_async(
+        CodexExecRequest(
+            prompt="TODO: streaming prompt",
+            sandbox=SandboxMode.READ_ONLY,
+            json_output=True,
+        )
+    )
+    async for event in live.iter_events():
+        print("event:", event.type)
+
+    final = await live.wait()
+    print("live turn_status:", final.turn_status)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

codex_sdk_python/data/skills/codex-local-sdk-usage/assets/template_live_stream.py

@@ -0,0 +1,28 @@
+"""Template: live JSON event streaming with CodexLocalClient.run_live."""
+
+from codex_local_sdk import CodexExecRequest, CodexLocalClient, SandboxMode
+
+
+def main() -> None:
+    client = CodexLocalClient()
+
+    live = client.run_live(
+        CodexExecRequest(
+            prompt="TODO: replace with your prompt",
+            sandbox=SandboxMode.READ_ONLY,
+            json_output=True,
+        )
+    )
+
+    print("pid:", live.pid)
+    for event in live.iter_events():
+        print("event:", event.type)
+
+    result = live.wait()
+    print("return_code:", result.return_code)
+    print("turn_status:", result.turn_status)
+    print("final_message:\n", result.final_message)
+
+
+if __name__ == "__main__":
+    main()

codex_sdk_python/data/skills/codex-local-sdk-usage/assets/template_resume_named_session.py

@@ -0,0 +1,35 @@
+"""Template: persist and resume a named session using JsonFileSessionStore."""
+
+from codex_local_sdk import CodexLocalClient, JsonFileSessionStore, SandboxMode
+
+
+def main() -> None:
+    store = JsonFileSessionStore(".codex_sessions.json")
+    client = CodexLocalClient(session_store=store)
+
+    session_name = "todo-session"
+
+    if client.get_session_id(session_name):
+        result = client.resume(
+            prompt="TODO: continue prompt",
+            session_name=session_name,
+            last=False,
+            json_output=True,
+            timeout_seconds=120,
+        )
+        print("resumed turn status:", result.turn_status)
+        print("resumed final message:\n", result.final_message)
+        return
+
+    session, first = client.start_thread(
+        prompt="TODO: initial prompt",
+        sandbox=SandboxMode.READ_ONLY,
+        session_name=session_name,
+        timeout_seconds=120,
+    )
+    print("created session:", session.session_name, session.session_id)
+    print("first turn status:", first.turn_status)
+
+
+if __name__ == "__main__":
+    main()

codex_sdk_python/data/skills/codex-local-sdk-usage/assets/template_schema_output.py

@@ -0,0 +1,41 @@
+"""Template: schema-constrained output with run_with_schema."""
+
+import json
+
+from codex_local_sdk import CodexLocalClient, SandboxMode
+
+
+def main() -> None:
+    client = CodexLocalClient()
+
+    schema = {
+        "type": "object",
+        "properties": {
+            "summary": {"type": "string"},
+            "actions": {
+                "type": "array",
+                "items": {"type": "string"},
+            },
+        },
+        "required": ["summary", "actions"],
+        "additionalProperties": False,
+    }
+
+    result = client.run_with_schema(
+        prompt="TODO: replace with your prompt",
+        schema=schema,
+        output_json_path="structured_output.json",
+        sandbox=SandboxMode.READ_ONLY,
+        timeout_seconds=120,
+    )
+
+    print("return_code:", result.return_code)
+    print("final_message:\n", result.final_message)
+
+    if result.final_message:
+        parsed = json.loads(result.final_message)
+        print("parsed keys:", sorted(parsed.keys()))
+
+
+if __name__ == "__main__":
+    main()

codex_sdk_python/data/skills/codex-local-sdk-usage/assets/template_sync_run.py

@@ -0,0 +1,24 @@
+"""Template: synchronous one-shot execution with CodexLocalClient.run."""
+
+from codex_local_sdk import CodexExecRequest, CodexLocalClient, SandboxMode
+
+
+def main() -> None:
+    client = CodexLocalClient()
+
+    request = CodexExecRequest(
+        prompt="TODO: replace with your prompt",
+        sandbox=SandboxMode.READ_ONLY,
+        json_output=True,
+    )
+
+    result = client.run(request, timeout_seconds=120)
+
+    print("return_code:", result.return_code)
+    print("turn_status:", result.turn_status)
+    print("thread_id:", result.thread_id)
+    print("final_message:\n", result.final_message)
+
+
+if __name__ == "__main__":
+    main()

codex_sdk_python/data/skills/codex-local-sdk-usage/assets/template_telemetry_and_retry.py

@@ -0,0 +1,56 @@
+"""Template: telemetry hook plus retry policy for robust sync execution."""
+
+from codex_local_sdk import (
+    CodexClientEvent,
+    CodexExecFailedError,
+    CodexExecRequest,
+    CodexLocalClient,
+    RetryPolicy,
+    SandboxMode,
+)
+
+
+def on_event(event: CodexClientEvent) -> None:
+    print(
+        event.type,
+        event.operation,
+        event.attempt,
+        event.return_code,
+        event.turn_status,
+    )
+
+
+def main() -> None:
+    client = CodexLocalClient(
+        retry_policy=RetryPolicy(
+            max_attempts=3,
+            initial_backoff_seconds=0.5,
+            backoff_multiplier=2.0,
+            max_backoff_seconds=4.0,
+            retry_on_exit_codes=None,
+            jitter_ratio=0.2,
+            max_total_retry_seconds=10.0,
+            retry_on_timeouts=True,
+        ),
+        event_hook=on_event,
+    )
+
+    request = CodexExecRequest(
+        prompt="TODO: replace with your prompt",
+        sandbox=SandboxMode.READ_ONLY,
+        json_output=True,
+    )
+
+    try:
+        result = client.run(request, timeout_seconds=60)
+    except CodexExecFailedError as exc:
+        print("failed return_code:", exc.result.return_code)
+        print("stderr:\n", exc.result.stderr)
+        return
+
+    print("success turn_status:", result.turn_status)
+    print("final_message:\n", result.final_message)
+
+
+if __name__ == "__main__":
+    main()

codex_sdk_python/data/skills/codex-local-sdk-usage/assets/template_thread_session.py

@@ -0,0 +1,29 @@
+"""Template: start a thread and continue it in-process."""
+
+from codex_local_sdk import CodexLocalClient, SandboxMode
+
+
+def main() -> None:
+    client = CodexLocalClient()
+
+    session, first = client.start_thread(
+        prompt="TODO: initial prompt",
+        sandbox=SandboxMode.READ_ONLY,
+        timeout_seconds=120,
+    )
+
+    print("session_id:", session.session_id)
+    print("first turn status:", first.turn_status)
+
+    second = session.continue_prompt(
+        "TODO: follow-up prompt",
+        json_output=True,
+        timeout_seconds=120,
+    )
+
+    print("second turn status:", second.turn_status)
+    print("second final message:\n", second.final_message)
+
+
+if __name__ == "__main__":
+    main()

codex_sdk_python/data/skills/codex-local-sdk-usage/references/guardrails-and-failure-modes.md

@@ -0,0 +1,55 @@
+# Guardrails and Failure Modes
+
+Use this file when generated consumer code fails or behaves unexpectedly.
+
+## Handle Non-Zero Exits Explicitly
+`CodexLocalClient` defaults to `raise_on_error=True`.
+
+```python
+from codex_local_sdk import CodexExecFailedError
+
+try:
+    result = client.run(request, timeout_seconds=90)
+except CodexExecFailedError as exc:
+    print(exc.result.return_code)
+    print(exc.result.stderr)
+```
+
+Set `raise_on_error=False` only when caller logic intentionally handles failed results directly.
+
+## Understand Timeout Behavior
+- Sync command execution uses `subprocess.run(..., timeout=timeout_seconds)`.
+- Timeout results are represented with return code `124`.
+- Retries on timeout follow `RetryPolicy.retry_on_timeouts`.
+
+## Tune Retries Pragmatically
+`RetryPolicy` applies to sync command execution (`run`, `resume`, `run_with_schema`, etc.):
+- `max_attempts`
+- `initial_backoff_seconds`
+- `backoff_multiplier`
+- `max_backoff_seconds`
+- `retry_on_exit_codes` (`None` means any non-zero)
+- `jitter_ratio`
+- `max_total_retry_seconds`
+- `retry_on_timeouts`
+
+Live methods only retry startup failures; they do not auto-retry after a live handle is returned.
+
+## Keep Session Calls Valid
+- Do not pass both `session_id` and `session_name`.
+- For named persistence, configure `JsonFileSessionStore` at client construction.
+- Use `last=False` when you want explicit session targeting instead of "last session" behavior.
+
+## Use Structured Output Deliberately
+- Set `json_output=True` when code depends on `events`, `thread_id`, or `turn_status`.
+- Use `run_with_schema` for machine-parseable outputs instead of fragile free-text parsing.
+
+## Observe Without Breaking Execution
+`event_hook` failures are swallowed by the SDK. Keep hooks lightweight and side-effect-safe.
+
+## Fast Triage Checklist
+1. Confirm `codex` exists in `PATH`.
+2. Confirm auth is available (`CODEX_API_KEY` or active local Codex auth).
+3. Print `result.stderr` and `result.return_code`.
+4. For event-dependent logic, verify `json_output=True`.
+5. For resume flows, verify stored `session_name` and session store file path.

codex_sdk_python/data/skills/codex-local-sdk-usage/references/sdk-api-cheatsheet.md

@@ -0,0 +1,72 @@
+# SDK API Cheatsheet
+
+Use this file to wire consumer code with correct classes and parameters.
+
+## Core Imports
+```python
+from codex_local_sdk import (
+    AsyncCodexLiveRun,
+    CodexClientEvent,
+    CodexExecFailedError,
+    CodexExecRequest,
+    CodexLocalClient,
+    CodexThreadSession,
+    JsonFileSessionStore,
+    RetryPolicy,
+    SandboxMode,
+)
+```
+
+## Request Model
+`CodexExecRequest` fields:
+- `prompt`
+- `cwd`
+- `json_output`
+- `model`
+- `profile`
+- `sandbox` (`SandboxMode.READ_ONLY`, `WORKSPACE_WRITE`, `DANGER_FULL_ACCESS`)
+- `full_auto`
+- `ephemeral`
+- `skip_git_repo_check`
+- `output_last_message_path`
+- `output_schema_path`
+- `images` (tuple of paths)
+- `extra_args` (tuple of additional CLI args)
+
+## Main Client Methods
+- `run(request, api_key=None, timeout_seconds=None) -> CodexExecResult`
+- `run_async(request, api_key=None, timeout_seconds=None) -> CodexExecResult`
+- `run_live(request, api_key=None) -> CodexLiveRun`
+- `run_live_async(request, api_key=None) -> AsyncCodexLiveRun`
+- `run_prompt(prompt, **kwargs) -> CodexExecResult`
+- `run_with_schema(prompt, schema, output_json_path=None, **kwargs) -> CodexExecResult`
+- `start_thread(prompt, session_name=None, timeout_seconds=None, **request_overrides) -> (CodexThreadSession, CodexExecResult)`
+- `resume(prompt, session_id=None, session_name=None, last=True, all_sessions=False, json_output=False, timeout_seconds=None) -> CodexExecResult`
+- `resume_live(prompt, session_id=None, session_name=None, last=True, all_sessions=False) -> CodexLiveRun`
+- `open_session(name) -> CodexThreadSession`
+
+## Thread Session Methods
+- `continue_prompt(prompt, json_output=True, timeout_seconds=None)`
+- `continue_prompt_async(prompt, json_output=True, timeout_seconds=None)`
+- `continue_live(prompt)`
+- `continue_live_async(prompt)`
+- `is_last_turn_complete`
+
+## Result Fields
+`CodexExecResult` includes:
+- `ok`
+- `return_code`
+- `stdout`
+- `stderr`
+- `final_message`
+- `thread_id`
+- `turn_status`
+- `usage`
+- `events`
+- `duration_seconds`
+- `is_turn_completed`, `is_turn_failed`, `is_turn_terminal`
+
+## Exception Types
+- `CodexNotInstalledError`: `codex` binary not available.
+- `CodexExecFailedError`: non-zero return code when `raise_on_error=True`.
+- `CodexError`: base exception.

codex_sdk_python/data/skills/codex-local-sdk-usage/references/task-routing.md

@@ -0,0 +1,26 @@
+# Task Routing
+
+Map user intent to the right SDK entry point before writing code.
+
+## Decision Table
+| User intent | Use these methods | Suggested template | Key setting |
+| --- | --- | --- | --- |
+| One-shot prompt and final text | `CodexLocalClient.run` or `run_prompt` | `template_sync_run.py` | `timeout_seconds` |
+| Require structured events and turn metadata | `run` with `CodexExecRequest(json_output=True)` | `template_sync_run.py` | `json_output=True` |
+| Stream live events as they happen | `run_live` | `template_live_stream.py` | Iterate `live.iter_events()` then `live.wait()` |
+| Continue multi-turn flow in one process | `start_thread` + `CodexThreadSession.continue_prompt` | `template_thread_session.py` | `start_thread` enforces JSON output |
+| Resume thread later by logical name | `JsonFileSessionStore` + `resume(session_name=..., last=False)` | `template_resume_named_session.py` | Reuse stable `session_name` |
+| Enforce JSON schema in assistant output | `run_with_schema` | `template_schema_output.py` | Provide strict schema and output path |
+| Use asyncio end-to-end | `run_async`, `run_live_async`, `continue_prompt_async` | `template_async_run.py` | `asyncio.run(main())` |
+| Add observability + retry policy | `CodexLocalClient(event_hook=..., retry_policy=...)` | `template_telemetry_and_retry.py` | Tune `RetryPolicy` |
+
+## Session Strategy
+- Use `session_id` for short-lived, in-memory flows.
+- Use `session_name` with `JsonFileSessionStore` for cross-process continuation.
+- Use `open_session(name)` when a session already exists and you want a `CodexThreadSession` handle.
+
+## Fallback Rules
+- If user needs only final text, avoid live mode.
+- If user needs incremental progress or event-level control, choose live mode.
+- If user requests "continue previous work" and no ID is provided, use named sessions.
+- If user needs machine-readable output, prefer schema flow over post-hoc parsing.

codex_sdk_python/data/skills/codex-local-sdk-usage/scripts/preflight_check.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Run quick environment checks before using codex_local_sdk in consumer scripts."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    status: str
+    detail: str
+
+
+def _discover_repo_root(start: Path) -> Path | None:
+    for candidate in (start, *start.parents):
+        if (candidate / "codex_local_sdk").is_dir():
+            return candidate
+    return None
+
+
+def _prepare_import_path() -> str | None:
+    root = _discover_repo_root(Path(__file__).resolve().parent)
+    if root is None:
+        return None
+
+    root_str = str(root)
+    if root_str not in sys.path:
+        sys.path.insert(0, root_str)
+    return root_str
+
+
+def check_python() -> CheckResult:
+    version = sys.version_info
+    detail = f"{version.major}.{version.minor}.{version.micro}"
+    if version >= (3, 10):
+        return CheckResult("python", "PASS", detail)
+    return CheckResult("python", "FAIL", f"{detail} (require >= 3.10)")
+
+
+def check_sdk_import() -> CheckResult:
+    repo_root = _prepare_import_path()
+    try:
+        module = importlib.import_module("codex_local_sdk")
+    except Exception as exc:  # pragma: no cover - defensive
+        return CheckResult("sdk_import", "FAIL", str(exc))
+
+    exported = getattr(module, "__all__", ())
+    detail = f"import ok; exports={len(tuple(exported))}"
+    if repo_root:
+        detail = f"{detail}; repo_root={repo_root}"
+    return CheckResult("sdk_import", "PASS", detail)
+
+
+def check_codex_cli() -> CheckResult:
+    codex_path = shutil.which("codex")
+    if not codex_path:
+        return CheckResult("codex_cli", "WARN", "`codex` not found in PATH")
+
+    try:
+        completed = subprocess.run(
+            [codex_path, "--version"],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except Exception as exc:  # pragma: no cover - defensive
+        return CheckResult("codex_cli", "WARN", f"found at {codex_path}; version probe failed: {exc}")
+
+    version_text = (completed.stdout or completed.stderr or "").strip() or "unknown version"
+    return CheckResult("codex_cli", "PASS", f"{codex_path}; {version_text}")
+
+
+def check_auth_hint() -> CheckResult:
+    if os.environ.get("CODEX_API_KEY"):
+        return CheckResult("auth", "PASS", "CODEX_API_KEY is set")
+    return CheckResult("auth", "WARN", "CODEX_API_KEY not set (ok if local Codex auth session is active)")
+
+
+def render(results: list[CheckResult]) -> int:
+    print("SDK consumer preflight")
+    print("======================")
+    for result in results:
+        print(f"[{result.status}] {result.name}: {result.detail}")
+
+    failed = any(r.status == "FAIL" for r in results)
+    warned = any(r.status == "WARN" for r in results)
+
+    if failed:
+        print("\nResult: not ready (hard failures detected)")
+        return 2
+    if warned:
+        print("\nResult: usable with warnings")
+        return 1
+
+    print("\nResult: ready")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check local readiness for codex_local_sdk consumer scripts.")
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit non-zero when warnings are present.",
+    )
+    args = parser.parse_args()
+
+    results = [
+        check_python(),
+        check_sdk_import(),
+        check_codex_cli(),
+        check_auth_hint(),
+    ]
+
+    code = render(results)
+    if code == 1 and not args.strict:
+        return 0
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex_sdk_python/data/skills/codex-local-sdk-usage/scripts/scaffold_usage_template.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Copy a codex_local_sdk usage template from assets/ into a target path."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def template_map(assets_dir: Path) -> dict[str, Path]:
+    return {
+        "sync": assets_dir / "template_sync_run.py",
+        "live": assets_dir / "template_live_stream.py",
+        "thread": assets_dir / "template_thread_session.py",
+        "resume": assets_dir / "template_resume_named_session.py",
+        "async": assets_dir / "template_async_run.py",
+        "schema": assets_dir / "template_schema_output.py",
+        "telemetry": assets_dir / "template_telemetry_and_retry.py",
+    }
+
+
+def list_templates(templates: dict[str, Path]) -> None:
+    print("Available templates:")
+    for key in sorted(templates):
+        print(f"- {key}: {templates[key].name}")
+
+
+def copy_template(source: Path, output: Path, force: bool) -> None:
+    if not source.exists():
+        raise FileNotFoundError(f"Template not found: {source}")
+
+    if output.exists() and not force:
+        raise FileExistsError(f"Output already exists: {output}. Pass --force to overwrite.")
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
+
+
+def main() -> int:
+    script_dir = Path(__file__).resolve().parent
+    assets_dir = script_dir.parent / "assets"
+    templates = template_map(assets_dir)
+
+    parser = argparse.ArgumentParser(description="Create a new consumer script from a usage template.")
+    parser.add_argument("--list", action="store_true", help="List template keys and exit.")
+    parser.add_argument("--template", choices=sorted(templates), help="Template key to copy.")
+    parser.add_argument("--output", help="Destination file path.")
+    parser.add_argument("--force", action="store_true", help="Overwrite output if it already exists.")
+    args = parser.parse_args()
+
+    if args.list:
+        list_templates(templates)
+        return 0
+
+    if not args.template or not args.output:
+        parser.error("--template and --output are required unless --list is used.")
+
+    source = templates[args.template]
+    destination = Path(args.output).expanduser().resolve()
+    copy_template(source, destination, force=args.force)
+    print(f"Wrote {destination} from {source.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())