feat: add headless conversation agent

[roackb2]

Stack

• base: feat: add conversation persistence capability #253 (codex/conversation-persistence-capability)
• this PR contains only SDK-13 headless onboarding and session-lifecycle changes
• merge feat: add conversation persistence capability #253 first, then rebase this branch onto main

Summary

• add ConversationAgentService as the smallest structured, in-process conversation entrypoint
• add race-safe engine.sessions.ensure({ id }) with create-or-read semantics across competing service instances
• return Heddle's normal structured turn result plus ordered captured activities and sessionCreated
• expose the underlying engine so adopters can progressively move to full session, turn, artifact, extension, and persistence control without rewriting
• share model/path/reasoning/memory defaults and credential preflight with the existing terminal quickstart, deleting its duplicated resolution logic
• add a runnable headless example and lead the English/Traditional Chinese onboarding docs with the new beginner path

Boundary

The service is deliberately headless and process-local. It does not own HTTP, authentication, tenant mapping, browser-safe projection, canonical product transactions, or durable in-flight execution. Returned turn data is trusted host data and must be projected before crossing an untrusted network boundary.

The default stable ID is session-1. Hosted/multi-user code must supply a trusted product-derived ID and scoped repositories. Ensure creation fields never overwrite an existing session.

Verification

• yarn test — 121 unit files / 715 tests; 34 integration files / 310 tests
• yarn typecheck
• yarn lint
• yarn build
• built-package import + stable ensure smoke
• 149 relative Markdown links resolved across changed docs
• real OpenAI first turn through ConversationAgentService: completed with 8 captured activities
• fresh service instance against the same state: resumed the original session, preserved its name, reported sessionCreated: false, reached 2 persisted turns, and recalled the first-turn phrase

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a0359c3b90

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preflight against the resumed session model

When a stable session already exists with a different model/provider than the current defaults, this constructor validates credentials for defaults.model before ensureSession() has read the persisted session, while the actual turn later resolves the runnable model from session.model. In that case a reusable session can be rejected because the default provider is missing credentials, or pass preflight and then fail during send() because the persisted provider is missing; perform preflight after ensure/read using the effective session model.

Useful? React with 👍 / 👎.