docs: propose a stable session export contract

[wey-gu]

Author type

• I am an Agent (check this if an LLM agent authored this PR)
• I am a human

Problem / pressure

Lody is becoming a workspace for conversations that are created and continued
from several clients and machines. External tools need a supported way to
consume the Lody-owned, user-visible session without scraping provider files or
mistaking an ACP runtime trace for the host conversation. The current CLI and
MCP history surfaces are useful for bounded reads, but do not yet define stable
event identity, incremental checkpoints, or delivery recovery semantics.

Summary

This proposal documents a provider-neutral session export contract and a
possible follow-up local delivery layer. It is intentionally design-first so
maintainers can confirm the API and package boundary before implementation.
It is non-normative: the example schema is illustrative, and there is no
backward-compatibility promise before a versioned v1 contract is published.

Related discussion: Lody issue #112.

Before / after

Before	After
External consumers must scrape provider state or poll UI-oriented history tools.	A proposed host-owned export contract gives consumers stable identity, cursors, provenance, and explicit visibility rules.
ACP runtime history is the most accessible integration surface, even though it cannot represent every Lody-authored message.	Lody remains the canonical conversation owner; ACP remains the execution protocol.
Real-time delivery would need to be invented independently by each consumer.	A later opt-in outbox or local stream can reuse the same durable event model.

Test plan

• git diff --check passed.
• Documentation-only change; no runtime tests apply.
• PR body format and affected-area checks are running in Lody CI.
• Local Prettier could not run because this checkout has no installed dependencies (pnpm exec prettier: command not found); this is recorded rather than presented as a passing check.

Agent handoff

Instructions for reviewing agents

• Review focus: Review docs/proposals/session-export-integrations.md for alignment with Lody's existing SessionMeta, SessionHistoryInput, workspace access, and local-first storage boundaries.
• Decisions to challenge: Decide whether pull export should precede delivery, where the public DTO belongs, and which choices must wait for the native Harness and Session ownership model.
• Plausible failures / evidence gaps: The proposal is not an implementation and does not yet prove a concrete export snapshot algorithm, attachment contract, or workspace-wide enumeration API.

Authoring context

• User goal / directives: Explore a close, reliable integration between Lody-hosted conversations and external knowledge/workflow tools, while contributing a design that fits Lody's own evolution.
• Constraints / non-goals: Keep the proposal vendor-neutral; do not add a Nowledge dependency, change ACP behavior, expose private storage, or claim that host-level Thread sync already exists.
• Risk-bearing decisions: Treat Lody as the canonical conversation owner, use stable event identity instead of text deduplication, preserve workspace/session visibility, and separate Agent Config provenance from durable identity.
• Destructive or irreversible behavior: None. This PR changes documentation only and adds no export, migration, webhook, or data movement behavior.
• Deliberately not done or tested: No runtime implementation or end-to-end export test is included until maintainers agree on the contract; full dependency-based formatting was unavailable in this checkout.
• Unknowns / confidence: High confidence in the problem boundary and non-goals; API naming, DTO package placement, exact snapshot semantics, and pre-v1 compatibility are intentionally open for maintainer review.

Sharing consent (author side)

• Author-side user explicitly allowed publishing the Authoring context above
• Author-side user explicitly declined publishing Authoring context and understands that maintainers may decline or close the contribution; keep every field as N/A / redacted

[wey-gu]

Related:

• [Feature Request] Define a stable session export contract #112 tracks the session export RFC and is the discussion record for this proposal.
• [Bug] Trusted PR policy workflows fail on stale base commits #111 tracks the trusted pull_request_target policy-workflow failure that currently prevents the contribution checks from evaluating this PR correctly.

These are process and review dependencies, not code dependencies: the CI fix should land independently, then this RFC can be updated to the current PR template and rechecked. No session-export implementation is implied by either issue.

[Leeeon233]

We are indeed planning to build our own harness.

However, regarding the capability to export sessions, we may need to give more long-term consideration to the extent and compatibility.

@wibus-wee what do you think?

[wibus-wee]

Thanks, I agree with this concern.

I think this proposal is useful now as a non-normative design RFC, but we should avoid turning the illustrative API into a stable v1 contract before the native Harness and Session ownership model are settled.

We can define the durable goals and boundaries now:

• Lody-owned user-visible projections
• runtime-neutral identity
• replay/recovery expectations
• privacy boundary.

The concrete event schema, cursor/watermark semantics, ordering under concurrent local-first writes, and delivery mechanism should remain open for now.

Once the Harness boundary is clearer, we can publish and implement a versioned v1 export contract with an explicit compatibility promise.

I would also suggest making it explicit in the RFC that the API examples are illustrative and that no backward-compatibility guarantee exists before v1.

[wibus-wee]

We have adjusted our PR strategy and will allow this PR to bypass our PR policy. Thank you, and sorry to bother you. :)

[wey-gu]

Respect all your decisions, please do not spend extra efforts on our side, just want to contribute and make Nowledge Mem community tight together with Lody Team.

Loved Lody ❤.