Skip to content

common-interfaces.md

Latest commit

 

History

History
103 lines (72 loc) · 3.18 KB

common-interfaces.md

File metadata and controls

103 lines (72 loc) · 3.18 KB

Shared Interfaces Between codex-session-transfer And codex-session-sync

This file is intentionally mirrored in:

  • codex-session-transfer/references/common-interfaces.md
  • codex-session-sync/references/common-interfaces.md

If either copy changes, treat that as a potential incompatibility risk and strongly recommend updating the counterpart copy in the same change.

Shared Interface 1: Local Session Working Set

Both skills must treat these objects as one coherent session unit:

  • rollout transcript jsonl
  • threads row in state_5.sqlite
  • session_index.jsonl entry
  • thread_dynamic_tools rows when present

Shared Interface 2: Package Root Layout

Both skills must understand this package structure as the baseline import surface:

session-skill-package/
  package_manifest.json
  README.md
  INSTALL_REMOTE.md
  metadata/
    threads.jsonl
    session_index.jsonl
    thread_dynamic_tools.jsonl
    path_localization.json
  sessions/
  skills/
  skeleton/
    required-directories.json

codex-session-sync may extend package interpretation, but should not silently break this baseline layout.

Shared Interface 3: Consumed Manifest Semantics

The following manifest semantics are shared:

  • format_version
  • package_kind
  • minimum_working_set_only
  • cwd_filter
  • thread_ids
  • skills_included
  • deferred_components
  • preferred_installer_skill

New sync-only fields should be additive and optional for transfer compatibility.

Shared Interface 4: Path Localization

For Windows paths, preserve the suffix starting at \\Documents\\ and replace the leading user-home prefix with the destination local home path.

If a path has no \\Documents\\ segment, leave it unchanged unless an explicit mapping is provided.

Shared Interface 5: Rollout Rewrite Surface

Any importer that materializes a local session copy may rewrite:

  • session_meta.id
  • session_meta.timestamp
  • session_meta.cwd
  • turn_context.cwd
  • turn_context.sandbox_policy.writable_roots
  • embedded user <environment_context> cwd values when present

Do not silently broaden transcript mutation without reflecting the change in both skills.

Shared Interface 6: Local Session Id Generation

When a new local session must be created, both skills should follow the same policy:

  • generate a new UUIDv7-based local session id
  • derive the target rollout path from the new id timestamp
  • preserve source sessions untouched

codex-session-sync may preserve an existing local session id only in fast-forward cases where no new branch session is created.

Shared Interface 7: Transaction Journal Semantics

Both skills should preserve the transaction-journal concept for reversible filesystem and metadata changes:

  • transaction id
  • creation timestamp
  • plan summary
  • backup inventory
  • reversible operations list
  • terminal status such as prepared, completed, or rolled_back

Shared Interface 8: Compatibility Warning Policy

If either skill modifies any shared interface listed here:

  1. mark the change as a potential incompatibility risk
  2. review the sibling skill for drift
  3. update the mirrored declaration in the sibling skill
  4. re-check docs, scripts, and handoff guidance for both skills