@kody/codex

@kody/codex

Thin, isolate-safe helpers for OpenAI's Agents API (managed Codex harness): create durable cloud agent sessions, continue turns, list items, and clean up.

Intent

Give agents and humans a pit-of-success way to create and manage Agents API sessions (POST https://api.openai.com/v1/agents/sessions with OpenAI-Beta: agents=v1) — Cursor/Devin-shaped cloud agents you create via API — without pretending to remote existing chatgpt.com/codex web threads or codex cloud CLI chats. Success means a working session create/list/get/input path with secret-backed auth and clear docs.

What this is / is not

Prerequisites

1. An OpenAI Platform API key with:
   • api.agents.read
   • api.agents.write
   • api.responses.write
2. Kody user secret openaiApiKey allowed for host api.openai.com: Create secret (prefilled)

Quick start

import openaiHosted from 'kody:@kody/codex/environments/openai-hosted'

const result = await openaiHosted({
  input:
    'Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.',
})
// result.sessionId — store with your conversation state

Or the generic create path:

import createSession from 'kody:@kody/codex/sessions/create'

const result = await createSession({
  agent: {
    model: 'gpt-6-astra', // docs placeholder — use a model your project allows
    instructions: 'Write clean code, run it, and report the actual output.',
  },
  environment: { type: 'openai_hosted' },
  input: 'Create tree.py, run it, and show the output.',
})

Core exports

Docs

• Agents API overview
• Quickstart
• Sessions
• Events and items

Visibility

Published private by default. Flip public via package visibility when you want it on /community (same pattern as @kody/browser-run after review).

License

MIT