Investigate Codex app-server as a Meld runtime integration

[ryuhmanov-m]

Context

Codex app-server is an important runtime target for the next Meld work cycle. Meld already has local-first vault access, agent tools, run traces, MCP-facing concepts, and an open issue for MCP Server mode (#22). This issue tracks a separate investigation: whether and how Meld should use, interoperate with, or learn from Codex app-server as a local agent runtime pattern.

Why this matters

• Meld's long-term promise is a shared Markdown knowledge environment for humans and AI agents, not just a chat UI over RAG.
• Codex app-server appears relevant as a practical local app/server runtime for agent sessions, tool orchestration, thread state, subprocesses, and long-lived local context.
• Before implementation, we need to separate proven reusable patterns from accidental Codex-internal details.

Questions to answer

• What exact surfaces does Codex app-server expose locally: API, process model, persistence, tool/session boundaries, and filesystem interaction?
• Which app-server concepts map cleanly to Meld's current architecture: vault tools, agent-space writes, hidden meta, run trace, provider registry, and MCP server mode?
• Should Meld integrate with Codex app-server directly, implement a compatible local runtime concept, or only borrow architecture patterns?
• What are the safety constraints for a local app-server that can read a vault and run tools?
• How does this relate to MCP Server mode: expose meld vault as tool provider for external agents #22 MCP Server mode?

Acceptance criteria

• Architecture note describing Codex app-server observations and whether it is an integration target, inspiration, or out-of-scope dependency.
• Proposed Meld runtime shape with boundaries for vault access, agent state, tool execution, logs/traces, and persistence.
• Decision on whether this becomes a product-relevant tech decision record in the knowledge base.
• Follow-up implementation issues split into small, testable units if the spike is positive.

Evidence to collect

• Local Codex app-server process/runtime behavior on the development machine.
• Any available official or local Codex documentation that describes app-server responsibilities.
• Comparison with Meld's existing Tauri/Rust runtime, MCP adapter, run trace, and vault zone model.

Related

• MCP Server mode: expose meld vault as tool provider for external agents #22
• Knowledge base: 20-projects/meld/

[ryuhmanov-m]

Official Codex docs update: this spike should explicitly evaluate both Codex app-server and the Codex SDK.

• Codex app-server is the right target for deep product integration: authentication, conversation history, approvals and streamed agent events. Docs: https://developers.openai.com/codex/app-server
• The Codex SDK is the better entry point for automation/CI/internal workflows. Docs: https://developers.openai.com/codex/sdk
• Important distinction from docs: if we are building a rich Meld integration, investigate app-server directly; if we need automation jobs or CI experiments, start through SDK.
• Python SDK controls the local Codex app-server over JSON-RPC and published builds include a pinned Codex CLI runtime dependency. That makes it useful for a quick spike before committing to a direct Rust/Tauri app-server client.

Acceptance criteria addition for this spike:

• Compare direct app-server JSON-RPC integration vs Codex SDK wrapper for Meld.
• Identify whether Meld should call app-server directly, use SDK for prototype/automation, or only borrow runtime patterns.
• Capture transport/security implications: stdio, Unix socket, websocket experimental status, auth requirements, sandbox settings and thread/turn/event model.

[ryuhmanov-m]

Schema evidence update, 2026-06-05:

• Local CLI checked: codex-cli 0.130.0.
• codex app-server generate-json-schema --out <dir> succeeded and produced 239 JSON Schema files.
• codex app-server generate-ts --out <dir> succeeded and produced 523 TypeScript files.
• Generated protocol includes thread/start, turn/start, thread resume/fork/read/list, item lifecycle notifications, approvals, MCP server/tool calls, filesystem/config/model surfaces and streamed server notifications.
• Product conclusion: app-server is a serious runtime candidate for Meld run trace / approval / thread-turn architecture, but direct Rust/Tauri integration remains unproven. Next spike should compare SDK-mediated prototype, direct stdio/Unix JSON-RPC client sketch and architecture-only borrowing. Meld memory claims/lifecycle must remain owned by Meld, not by Codex thread history.

Vault note: 20-projects/meld/10-product-relevant-tech/codex-app-server-evidence-matrix-2026-06-05.md

[ryuhmanov-m]

Current spike recommendation after the 2026-06-05 docs/source pass:

• First governed-memory proof should stay on Meld-owned primitives: source -> gate -> memory card -> correction -> later-use -> audit.
• Codex app-server remains a serious runtime candidate, but not the dependency for the first proof.
• Use SDK/schema/stdio learning first to observe thread/turn/item/event/approval/sandbox behavior.
• Treat architecture-only borrowing as the current safest baseline because local meld-app already has Tauri commands, Rust agent loop, provider adapter, internal tool registry, run ledger/UI trace, zones, provenance and readback verification.
• Promote direct app-server integration only after transport, schema pinning, approval/sandbox mapping, event mapping, failure handling, security/auth and persistence boundaries pass.
• Codex thread history must not become Meld memory; Meld keeps ownership of memory claims, storage policy, lifecycle state, correction, personal-model persistence and Comic Paper OS product language.

Durable vault notes added:

• 20-projects/meld/10-product-relevant-tech/codex-runtime-spike-outcome-2026-06-05.md
• 20-projects/meld/04-ux-ui/comic-paper-component-contract-2026-06-05.md