@kody/codex

import {
	DEFAULT_API_KEY_SECRET,
	DOCS_DEFAULT_MODEL,
	DOCS_EVENTS,
	DOCS_MANAGE,
	DOCS_OVERVIEW,
	DOCS_QUICKSTART,
	DOCS_SESSIONS,
	KEY_PERMISSIONS,
	LIMITATION_NOTE,
	TOKEN_SETUP_URL,
} from './client.ts'

/**
 * Package overview for OpenAI Agents API (Codex harness).
 * Prefer `./sessions/create` or `./environments/openai-hosted` to start a
 * cloud agent session. Does not remote ChatGPT/codex web or CLI chats.
 *
 * @returns Discovery metadata: exports, secrets, docs, and pit-of-success notes.
 *
 * @example
 * import overview from 'kody:@kody/codex'
 * const meta = await overview()
 * // => { name: '@kody/codex', pitOfSuccess: { … }, exports: [ … ] }
 */
export default async function overview() {
	return {
		name: '@kody/codex',
		packageId: 'a66e5e75-748e-4e15-9536-5ffc1edf8274',
		listingUrl: 'https://kody.codes/@kody/codex',
		description:
			'Create and manage OpenAI Agents API (Codex harness) cloud agent sessions.',
		limitation: LIMITATION_NOTE,
		docs: {
			overview: DOCS_OVERVIEW,
			quickstart: DOCS_QUICKSTART,
			sessions: DOCS_SESSIONS,
			manage: DOCS_MANAGE,
			events: DOCS_EVENTS,
		},
		secrets: {
			defaultSecret: DEFAULT_API_KEY_SECRET,
			setupUrl: TOKEN_SETUP_URL,
			permissions: [...KEY_PERMISSIONS],
			host: 'api.openai.com',
			betaHeader: 'OpenAI-Beta: agents=v1',
			optionalApiKeySecret:
				'Pass apiKeySecret with an alternate Kody secret **name** only when not using openaiApiKey.',
		},
		concepts: {
			agent: 'Model, instructions, tools, and MCP servers available to the agent.',
			environment:
				'Sandbox or computer: openai_hosted | self_hosted | none. OpenAI provisions openai_hosted.',
			session: 'Durable instance of an agent that works on tasks and responds to input.',
			eventsAndItems:
				'Live progress (events) and saved messages/tool calls (items). Streams do not replay; recover via get + items.',
		},
		pitOfSuccess: {
			defaultCreatePath: './sessions/create',
			openaiHostedQuickstart: './environments/openai-hosted',
			alwaysBetaHeader: 'OpenAI-Beta: agents=v1',
			defaultModelPlaceholder: DOCS_DEFAULT_MODEL,
			modelNote:
				'Docs examples use gpt-6-astra — pass a model available on your project; do not invent ids.',
			followUp: 'Subscribe/stream before POST sessions/{id}/events for follow-up input.',
			terminalEvents: [
				'agent.session.turn.completed',
				'agent.session.turn.failed',
				'agent.session.turn.cancelled',
			],
			idleIsNotSuccess:
				'agent.session.idle alone does not mean the turn succeeded — inspect output/items.',
			notChatgptThreads: true,
		},
		whenToUse: {
			create:
				'Main path: create a session with agent + environment + input (optionally stream first turn).',
			openaiHosted:
				'Thin wrapper for the quickstart openai_hosted sandbox coding agent.',
			selfHosted:
				'Recipe/metadata for self_hosted environments (workspace_directory, capability_directories) — not a fake browser.',
			input: 'Continue or steer an existing session with agent.session.input.message.',
			stream:
				'Guidance + bounded SSE collect for GET .../events?stream=true (prefer short maxEvents in isolates).',
			smokeTest: 'Dry setup guidance or read-only list sessions after secret is wired.',
		},
		exports: [
			{ subpath: '.', purpose: 'Overview / discovery' },
			{ subpath: './overview', purpose: 'Alias of root overview' },
			{ subpath: './sessions/create', purpose: 'POST /v1/agents/sessions (main path)' },
			{ subpath: './sessions/get', purpose: 'GET /v1/agents/sessions/{session_id}' },
			{ subpath: './sessions/list', purpose: 'GET /v1/agents/sessions' },
			{ subpath: './sessions/delete', purpose: 'DELETE session (confirm/dryRun)' },
			{ subpath: './sessions/input', purpose: 'POST follow-up / cancel events' },
			{ subpath: './sessions/items', purpose: 'GET saved session items' },
			{ subpath: './events/stream', purpose: 'Stream guidance + bounded SSE helper' },
			{
				subpath: './environments/openai-hosted',
				purpose: 'Quickstart openai_hosted create wrapper',
			},
			{
				subpath: './environments/self-hosted',
				purpose: 'self_hosted recipe metadata (not runnable remote)',
			},
			{ subpath: './smoke-test', purpose: 'Setup guidance / list-sessions smoke' },
		],
	}
}