@kody/codex

Create and manage OpenAI Agents API (Codex harness) cloud agent sessions.

AGENTS.md

82 lines · 3.0 KB · Markdown

@kody/codex — agent notes

Human setup and intent: README.md. Prefer static kody:@kody/codex/… imports from execute. Never packages.invoke.

Scope boundary (critical)

This package talks to OpenAI Agents API only:

POST/GET/DELETE https://api.openai.com/v1/agents/sessions…
Header OpenAI-Beta: agents=v1 on every call

It does not remote-control chatgpt.com/codex UI threads or codex cloud CLI chats. Do not scrape ChatGPT tasks.

Secrets

Name	Notes
`openaiApiKey`	Default. Platform key with `api.agents.read`, `api.agents.write`, `api.responses.write`. Host: `api.openai.com`.
`apiKeySecret` param	Alternate secret name only — not a key value.

Setup URL (prefilled): https://kody.codes/account/secrets/new?name=openaiApiKey&description=OpenAI%20API%20key%20with%20api.agents.read%2C%20api.agents.write%2C%20api.responses.write&allowedHosts=api.openai.com&scope=user

Import table

Export	Import
overview	`kody:@kody/codex`
sessions/create	`kody:@kody/codex/sessions/create`
sessions/get	`kody:@kody/codex/sessions/get`
sessions/list	`kody:@kody/codex/sessions/list`
sessions/delete	`kody:@kody/codex/sessions/delete`
sessions/input	`kody:@kody/codex/sessions/input`
sessions/items	`kody:@kody/codex/sessions/items`
events/stream	`kody:@kody/codex/events/stream`
environments/openai-hosted	`kody:@kody/codex/environments/openai-hosted`
environments/self-hosted	`kody:@kody/codex/environments/self-hosted`
smoke-test	`kody:@kody/codex/smoke-test`

Pit of success

After publish: smoke-test with { dryRun: true }, then live list once the secret exists (dryRun: false).
Create with environments/openai-hosted or sessions/create.
Store sessionId. For follow-ups: open stream guidance / stream first, then sessions/input with text.
After disconnect: sessions/get + sessions/items (streams do not replay).
Delete only with confirm: true after saving artifacts (dryRun first).

Runtime input checking

Exposed exports use remix/data-schema with { unknownKeys: 'error' }. Do not invent aliases. Destructive delete requires confirm: true.

Models

Docs examples use gpt-6-astra as a placeholder. Pass a model id available on the caller's OpenAI project — do not invent model names.

Smoke tests

import smokeTest from 'kody:@kody/codex/smoke-test'
await smokeTest({ dryRun: true })

import createSession from 'kody:@kody/codex/sessions/create'
await createSession({
  dryRun: true,
  agent: { model: 'gpt-6-astra', instructions: 'Be concise.' },
  environment: { type: 'openai_hosted' },
  input: 'Say hello.',
})

Edge cases

environment.type: "none" requires initial input.
agent.session.idle ≠ success; look for turn completed/failed/cancelled.
Long SSE: prefer events/stream guidance; collect: true is bounded only.
Self-hosted export is recipe metadata — not a remote computer implementation.