kartik-mem0
1493 lines
60 KiB
Python
1493 lines
60 KiB
Python
#!/usr/bin/env python3
|
|
"""Shared local session-handoff engine and backwards-compatible Claude CLI.
|
|
|
|
Native readers and SDK adapters supply complete conversation items. This engine
|
|
validates and exports their bundles, then uses Codex's native external-session
|
|
importer to create a task with visible historical turns. The legacy command
|
|
still defaults to reading a Claude Code transcript; session_handoff.py requires
|
|
an explicit source host or a neutral bundle.
|
|
|
|
No model generates a handoff summary. Large imports may use Codex's native
|
|
compaction before the new task is returned.
|
|
"""
|
|
|
|
# Adapted from mem0ai/memo at aeeb1593284d1d2fca3b4bcf1e32ea10f71df549 (Apache-2.0).
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import base64
|
|
import binascii
|
|
import hashlib
|
|
import html
|
|
import json
|
|
import os
|
|
import queue
|
|
import re
|
|
import shutil
|
|
import subprocess
|
|
import sys
|
|
import tempfile
|
|
import threading
|
|
import time
|
|
from dataclasses import asdict, dataclass, replace
|
|
from pathlib import Path
|
|
from typing import Any, Iterable
|
|
|
|
FORMAT_VERSION = "mem0.session-handoff.v1"
|
|
DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex")))
|
|
DEFAULT_BUNDLE_DIR = Path.home() / ".mem0" / "handoffs"
|
|
IMPORT_COMPLETED_NOTIFICATION = "externalAgentConfig/import/completed"
|
|
IMAGE_EXTENSIONS = {
|
|
"image/gif": "gif",
|
|
"image/jpeg": "jpg",
|
|
"image/png": "png",
|
|
"image/webp": "webp",
|
|
}
|
|
|
|
|
|
class HandoffError(RuntimeError):
|
|
"""A source session cannot be transferred without losing state."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class SourceInfo:
|
|
path: str
|
|
sha256: str
|
|
session_id: str
|
|
title: str
|
|
cwd: str
|
|
leaf_uuid: str
|
|
compact_boundary_uuid: str | None
|
|
first_imported_uuid: str
|
|
last_imported_uuid: str
|
|
codex_cwd: str | None = None
|
|
host: str = "claude-code"
|
|
|
|
|
|
@dataclass
|
|
class HandoffPlan:
|
|
source: SourceInfo
|
|
items: list[dict[str, Any]]
|
|
source_records: int
|
|
active_records: int
|
|
imported_records: int
|
|
hidden_reasoning_blocks_skipped: int
|
|
approximate_tokens: int
|
|
warnings: list[str]
|
|
|
|
def bundle(self) -> dict[str, Any]:
|
|
return {
|
|
"format": FORMAT_VERSION,
|
|
"source": asdict(self.source),
|
|
"items": self.items,
|
|
"counts": {
|
|
"source_records": self.source_records,
|
|
"active_records": self.active_records,
|
|
"imported_records": self.imported_records,
|
|
"responses_items": len(self.items),
|
|
"hidden_reasoning_blocks_skipped": self.hidden_reasoning_blocks_skipped,
|
|
"approximate_tokens": self.approximate_tokens,
|
|
},
|
|
"warnings": self.warnings,
|
|
}
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class CodexContextLimits:
|
|
model: str
|
|
context_window: int
|
|
usable_context_window: int
|
|
auto_compact_token_limit: int
|
|
max_context_window: int
|
|
max_usable_context_window: int
|
|
max_auto_compact_token_limit: int
|
|
|
|
|
|
def _stable_jsonl(path: Path) -> tuple[list[dict[str, Any]], str]:
|
|
before = path.stat()
|
|
raw = path.read_bytes()
|
|
after = path.stat()
|
|
if (before.st_size, before.st_mtime_ns) != (after.st_size, after.st_mtime_ns):
|
|
raise HandoffError(f"Source session changed while it was being read: {path}")
|
|
if raw and not raw.endswith(b"\n"):
|
|
raise HandoffError(
|
|
"The final JSONL record is incomplete. Finish or stop the active source response before transferring it."
|
|
)
|
|
|
|
records: list[dict[str, Any]] = []
|
|
for line_number, line in enumerate(raw.splitlines(), 1):
|
|
if not line.strip():
|
|
continue
|
|
try:
|
|
record = json.loads(line)
|
|
except json.JSONDecodeError as exc:
|
|
raise HandoffError(f"Invalid source JSONL at {path}:{line_number}: {exc}") from exc
|
|
if not isinstance(record, dict):
|
|
raise HandoffError(f"Source JSONL record is not an object at {path}:{line_number}.")
|
|
records.append(record)
|
|
if not records:
|
|
raise HandoffError(f"Source session is empty: {path}")
|
|
return records, hashlib.sha256(raw).hexdigest()
|
|
|
|
|
|
def _resolve_session(value: str, projects_dir: Path) -> Path:
|
|
supplied = Path(value).expanduser()
|
|
if supplied.is_file():
|
|
return supplied.resolve()
|
|
|
|
matches = list(projects_dir.glob(f"*/{value}.jsonl"))
|
|
if not matches:
|
|
raise HandoffError(
|
|
f"No Claude session named {value!r} exists below {projects_dir}. "
|
|
"Pass the session ID or its full JSONL path."
|
|
)
|
|
if len(matches) != 1:
|
|
joined = "\n".join(f" {path}" for path in matches)
|
|
raise HandoffError(f"Session ID {value!r} is ambiguous:\n{joined}")
|
|
return matches[0].resolve()
|
|
|
|
|
|
def _active_chain(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
|
with_uuid = [
|
|
record for record in records if isinstance(record.get("uuid"), str) and record.get("isSidechain") is not True
|
|
]
|
|
if not with_uuid:
|
|
raise HandoffError("Claude session has no main-agent conversation records.")
|
|
|
|
by_uuid = {record["uuid"]: record for record in with_uuid}
|
|
leaf = with_uuid[-1]
|
|
chain: list[dict[str, Any]] = []
|
|
seen: set[str] = set()
|
|
current: dict[str, Any] | None = leaf
|
|
while current is not None:
|
|
uuid = current["uuid"]
|
|
if uuid in seen:
|
|
raise HandoffError(f"Claude session contains a parent cycle at {uuid}.")
|
|
seen.add(uuid)
|
|
chain.append(current)
|
|
parent_uuid = current.get("parentUuid")
|
|
if parent_uuid is None:
|
|
break
|
|
current = by_uuid.get(parent_uuid)
|
|
if current is None:
|
|
raise HandoffError(f"Claude's active branch references missing parent {parent_uuid}.")
|
|
chain.reverse()
|
|
return chain
|
|
|
|
|
|
def _after_latest_compaction(
|
|
chain: list[dict[str, Any]],
|
|
) -> tuple[list[dict[str, Any]], str | None]:
|
|
compact_index: int | None = None
|
|
for index, record in enumerate(chain):
|
|
if record.get("type") == "system" and record.get("subtype") == "compact_boundary":
|
|
compact_index = index
|
|
if compact_index is None:
|
|
imported = chain
|
|
compact_uuid = None
|
|
else:
|
|
imported = chain[compact_index + 1 :]
|
|
compact_uuid = chain[compact_index]["uuid"]
|
|
if not imported or imported[0].get("isCompactSummary") is not True:
|
|
raise HandoffError(f"Claude compaction {compact_uuid} has no following compact summary.")
|
|
imported = [record for record in imported if record.get("type") != "system"]
|
|
if not imported:
|
|
raise HandoffError("Claude's active state contains no transferable records.")
|
|
return imported, compact_uuid
|
|
|
|
|
|
def _tool_result_ids(record: dict[str, Any]) -> set[str]:
|
|
if record.get("type") != "user":
|
|
return set()
|
|
content = (record.get("message") or {}).get("content")
|
|
if not isinstance(content, list):
|
|
return set()
|
|
return {
|
|
str(block["tool_use_id"])
|
|
for block in content
|
|
if isinstance(block, dict) and block.get("type") == "tool_result" and block.get("tool_use_id")
|
|
}
|
|
|
|
|
|
def _tool_call_ids(records: list[dict[str, Any]]) -> set[str]:
|
|
call_ids: set[str] = set()
|
|
for record in records:
|
|
if record.get("type") != "assistant":
|
|
continue
|
|
content = (record.get("message") or {}).get("content")
|
|
if not isinstance(content, list):
|
|
continue
|
|
call_ids.update(
|
|
str(block["id"])
|
|
for block in content
|
|
if isinstance(block, dict) and block.get("type") == "tool_use" and block.get("id")
|
|
)
|
|
return call_ids
|
|
|
|
|
|
def _merge_parallel_tool_results(
|
|
active_records: list[dict[str, Any]], all_records: list[dict[str, Any]]
|
|
) -> list[dict[str, Any]]:
|
|
"""Restore sibling tool results that Claude stores outside the parent chain.
|
|
|
|
Parallel Claude tool calls form a fork: later calls remain on the parent
|
|
chain, while earlier results can be sibling records. Claude sends all of
|
|
those results back to the model. Insert them together immediately after the
|
|
assistant response that issued the calls.
|
|
"""
|
|
results_by_call: dict[str, list[tuple[int, dict[str, Any]]]] = {}
|
|
for source_index, record in enumerate(all_records):
|
|
for call_id in _tool_result_ids(record):
|
|
results_by_call.setdefault(call_id, []).append((source_index, record))
|
|
|
|
merged: list[dict[str, Any]] = []
|
|
inserted_result_uuids: set[str] = set()
|
|
index = 0
|
|
while index < len(active_records):
|
|
record = active_records[index]
|
|
record_uuid = str(record.get("uuid") or "")
|
|
if record_uuid in inserted_result_uuids:
|
|
index += 1
|
|
continue
|
|
if record.get("type") != "assistant":
|
|
merged.append(record)
|
|
index += 1
|
|
continue
|
|
|
|
message_id = (record.get("message") or {}).get("id")
|
|
group = [record]
|
|
index += 1
|
|
while index < len(active_records):
|
|
candidate = active_records[index]
|
|
candidate_id = (candidate.get("message") or {}).get("id")
|
|
if candidate.get("type") != "assistant" or not message_id or candidate_id != message_id:
|
|
break
|
|
group.append(candidate)
|
|
index += 1
|
|
merged.extend(group)
|
|
|
|
matching_results: list[tuple[int, dict[str, Any]]] = []
|
|
for call_id in _tool_call_ids(group):
|
|
matching_results.extend(results_by_call.get(call_id, []))
|
|
for _, result in sorted(matching_results, key=lambda pair: pair[0]):
|
|
result_uuid = str(result.get("uuid") or "")
|
|
if result_uuid and result_uuid not in inserted_result_uuids:
|
|
merged.append(result)
|
|
inserted_result_uuids.add(result_uuid)
|
|
return merged
|
|
|
|
|
|
def _image_payload(source: Any, context: str) -> tuple[str, str]:
|
|
if not isinstance(source, dict) or source.get("type") != "base64":
|
|
raise HandoffError(f"{context} is not stored as transferable base64 data.")
|
|
media_type = str(source.get("media_type") or "").lower()
|
|
data = source.get("data")
|
|
if media_type not in IMAGE_EXTENSIONS or not isinstance(data, str) or not data:
|
|
raise HandoffError(f"{context} has an unsupported or missing image type.")
|
|
return media_type, data
|
|
|
|
|
|
def _data_url_payload(image_url: Any, context: str) -> tuple[str, str]:
|
|
if not isinstance(image_url, str):
|
|
raise HandoffError(f"{context} has no transferable image data.")
|
|
match = re.fullmatch(r"data:([^;,]+);base64,(.+)", image_url, flags=re.DOTALL)
|
|
if not match:
|
|
raise HandoffError(f"{context} is not stored as transferable base64 data.")
|
|
media_type = match.group(1).lower()
|
|
if media_type not in IMAGE_EXTENSIONS:
|
|
raise HandoffError(f"{context} has unsupported image type {media_type!r}.")
|
|
return media_type, match.group(2)
|
|
|
|
|
|
def _save_image(
|
|
media_type: str,
|
|
encoded: str,
|
|
asset_dir: Path,
|
|
context: str,
|
|
) -> Path:
|
|
try:
|
|
payload = base64.b64decode(encoded, validate=True)
|
|
except (binascii.Error, ValueError) as exc:
|
|
raise HandoffError(f"{context} contains invalid base64 image data.") from exc
|
|
if not payload:
|
|
raise HandoffError(f"{context} contains an empty image.")
|
|
|
|
digest = hashlib.sha256(payload).hexdigest()
|
|
asset_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
path = asset_dir / f"{digest}.{IMAGE_EXTENSIONS[media_type]}"
|
|
if path.exists():
|
|
if hashlib.sha256(path.read_bytes()).hexdigest() != digest:
|
|
raise HandoffError(f"The existing handoff image is corrupted: {path}")
|
|
return path
|
|
|
|
descriptor, filename = tempfile.mkstemp(prefix=f".{path.name}.", dir=asset_dir)
|
|
temporary = Path(filename)
|
|
try:
|
|
with os.fdopen(descriptor, "wb") as stream:
|
|
stream.write(payload)
|
|
os.replace(temporary, path)
|
|
except OSError as exc:
|
|
temporary.unlink(missing_ok=True)
|
|
raise HandoffError(f"Could not save the handoff image at {path}: {exc}") from exc
|
|
return path
|
|
|
|
|
|
def _image_reference(
|
|
media_type: str,
|
|
encoded: str,
|
|
asset_dir: Path,
|
|
context: str,
|
|
) -> str:
|
|
path = _save_image(media_type, encoded, asset_dir, context)
|
|
return f"[Image saved at {path}]"
|
|
|
|
|
|
def _tool_result_text(value: Any, asset_dir: Path, context: str) -> str:
|
|
if value is None:
|
|
return ""
|
|
if isinstance(value, str):
|
|
return value
|
|
if isinstance(value, (int, float, bool)):
|
|
return str(value)
|
|
if isinstance(value, list):
|
|
parts: list[str] = []
|
|
for part in value:
|
|
if isinstance(part, dict) and part.get("type") == "text":
|
|
parts.append(str(part.get("text", "")))
|
|
elif isinstance(part, dict) and part.get("type") == "image":
|
|
media_type, encoded = _image_payload(part.get("source"), context)
|
|
parts.append(_image_reference(media_type, encoded, asset_dir, context))
|
|
else:
|
|
parts.append(json.dumps(part, ensure_ascii=False, separators=(",", ":")))
|
|
return "\n".join(part for part in parts if part)
|
|
if isinstance(value, dict) and value.get("type") == "image":
|
|
media_type, encoded = _image_payload(value.get("source"), context)
|
|
return _image_reference(media_type, encoded, asset_dir, context)
|
|
return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
|
|
|
|
|
|
def _message(role: str, parts: list[dict[str, Any]]) -> dict[str, Any]:
|
|
return {"type": "message", "role": role, "content": parts}
|
|
|
|
|
|
def _attachment_item(record: dict[str, Any]) -> dict[str, Any] | None:
|
|
attachment = record.get("attachment")
|
|
if not isinstance(attachment, dict):
|
|
raise HandoffError(f"Claude attachment {record.get('uuid')} has no payload.")
|
|
|
|
attachment_type = attachment.get("type")
|
|
filename = str(attachment.get("filename") or attachment.get("displayPath") or "unknown")
|
|
content = attachment.get("content")
|
|
if attachment_type == "file" and isinstance(content, dict):
|
|
file_payload = content.get("file") if content.get("type") == "text" else None
|
|
if isinstance(file_payload, dict) and isinstance(file_payload.get("content"), str):
|
|
text = file_payload["content"]
|
|
display = str(file_payload.get("filePath") or filename)
|
|
wrapped = f'<claude_attachment path="{display}">\n{text}\n</claude_attachment>'
|
|
return _message("user", [{"type": "input_text", "text": wrapped}])
|
|
|
|
if attachment_type == "image" and isinstance(content, dict):
|
|
image_url = content.get("image_url") or content.get("data")
|
|
if isinstance(image_url, str) and image_url.startswith("data:"):
|
|
return _message("user", [{"type": "input_image", "image_url": image_url}])
|
|
|
|
if attachment_type in {"file", "image"}:
|
|
raise HandoffError(f"Claude {attachment_type} attachment {record.get('uuid')} has an unsupported payload.")
|
|
|
|
# Claude also records its own skill list, tool availability, permissions,
|
|
# token reminders, hooks, and task status as attachments. Those configure
|
|
# Claude's harness; they are not part of the user's project conversation and
|
|
# must not become user messages in Codex.
|
|
return None
|
|
|
|
|
|
def _assistant_items(records: list[dict[str, Any]], calls: dict[str, str]) -> tuple[list[dict[str, Any]], int]:
|
|
items: list[dict[str, Any]] = []
|
|
skipped_reasoning = 0
|
|
text_parts: list[dict[str, Any]] = []
|
|
|
|
def flush_text() -> None:
|
|
if text_parts:
|
|
items.append(_message("assistant", list(text_parts)))
|
|
text_parts.clear()
|
|
|
|
for record in records:
|
|
content = (record.get("message") or {}).get("content", [])
|
|
if isinstance(content, str):
|
|
text_parts.append({"type": "output_text", "text": content})
|
|
continue
|
|
if not isinstance(content, list):
|
|
raise HandoffError(f"Claude assistant record {record.get('uuid')} has invalid content.")
|
|
for block in content:
|
|
if not isinstance(block, dict):
|
|
raise HandoffError(f"Claude assistant record {record.get('uuid')} has invalid block.")
|
|
kind = block.get("type")
|
|
if kind == "thinking" or kind == "redacted_thinking":
|
|
skipped_reasoning += 1
|
|
continue
|
|
if kind == "text":
|
|
text_parts.append({"type": "output_text", "text": str(block.get("text", ""))})
|
|
continue
|
|
if kind == "tool_use":
|
|
flush_text()
|
|
call_id = str(block.get("id") or "")
|
|
name = str(block.get("name") or "")
|
|
if not call_id or not name:
|
|
raise HandoffError(f"Claude tool call in {record.get('uuid')} has no ID or name.")
|
|
if call_id in calls:
|
|
raise HandoffError(f"Claude tool call ID is duplicated: {call_id}")
|
|
calls[call_id] = name
|
|
items.append(
|
|
{
|
|
"type": "function_call",
|
|
"call_id": call_id,
|
|
"name": name,
|
|
"arguments": json.dumps(
|
|
block.get("input", {}),
|
|
ensure_ascii=False,
|
|
separators=(",", ":"),
|
|
),
|
|
}
|
|
)
|
|
continue
|
|
raise HandoffError(f"Unsupported Claude assistant block {kind!r} in {record.get('uuid')}.")
|
|
flush_text()
|
|
return items, skipped_reasoning
|
|
|
|
|
|
def _user_items(record: dict[str, Any], calls: dict[str, str], completed_calls: set[str]) -> list[dict[str, Any]]:
|
|
if record.get("isMeta") is True:
|
|
return []
|
|
content = (record.get("message") or {}).get("content")
|
|
if isinstance(content, str):
|
|
return [_message("user", [{"type": "input_text", "text": content}])]
|
|
if not isinstance(content, list):
|
|
raise HandoffError(f"Claude user record {record.get('uuid')} has invalid content.")
|
|
|
|
items: list[dict[str, Any]] = []
|
|
user_parts: list[dict[str, Any]] = []
|
|
|
|
def flush_user() -> None:
|
|
if user_parts:
|
|
items.append(_message("user", list(user_parts)))
|
|
user_parts.clear()
|
|
|
|
for block in content:
|
|
if not isinstance(block, dict):
|
|
raise HandoffError(f"Claude user record {record.get('uuid')} has invalid block.")
|
|
kind = block.get("type")
|
|
if kind == "text":
|
|
user_parts.append({"type": "input_text", "text": str(block.get("text", ""))})
|
|
continue
|
|
if kind == "image":
|
|
source = block.get("source") or {}
|
|
if source.get("type") == "base64" and source.get("data") and source.get("media_type"):
|
|
user_parts.append(
|
|
{
|
|
"type": "input_image",
|
|
"image_url": f"data:{source['media_type']};base64,{source['data']}",
|
|
}
|
|
)
|
|
continue
|
|
raise HandoffError(f"Claude image in {record.get('uuid')} is not stored as transferable base64 data.")
|
|
if kind == "tool_result":
|
|
flush_user()
|
|
call_id = str(block.get("tool_use_id") or "")
|
|
if not call_id:
|
|
raise HandoffError(f"Claude tool result in {record.get('uuid')} has no call ID.")
|
|
if call_id not in calls:
|
|
raise HandoffError(f"Claude tool result {call_id} has no matching call in the active state.")
|
|
if call_id in completed_calls:
|
|
raise HandoffError(f"Claude tool result is duplicated: {call_id}")
|
|
completed_calls.add(call_id)
|
|
items.append(
|
|
{
|
|
"type": "function_call_output",
|
|
"call_id": call_id,
|
|
"name": calls[call_id],
|
|
"output": block.get("content"),
|
|
}
|
|
)
|
|
continue
|
|
raise HandoffError(f"Unsupported Claude user block {kind!r} in {record.get('uuid')}.")
|
|
flush_user()
|
|
return items
|
|
|
|
|
|
def _responses_items(records: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], int]:
|
|
items: list[dict[str, Any]] = []
|
|
calls: dict[str, str] = {}
|
|
completed_calls: set[str] = set()
|
|
skipped_reasoning = 0
|
|
|
|
index = 0
|
|
while index < len(records):
|
|
record = records[index]
|
|
record_type = record.get("type")
|
|
if record_type == "assistant":
|
|
message_id = (record.get("message") or {}).get("id")
|
|
group = [record]
|
|
index += 1
|
|
while index < len(records):
|
|
candidate = records[index]
|
|
if candidate.get("type") != "assistant":
|
|
break
|
|
candidate_id = (candidate.get("message") or {}).get("id")
|
|
if not message_id or candidate_id != message_id:
|
|
break
|
|
group.append(candidate)
|
|
index += 1
|
|
assistant_items, skipped = _assistant_items(group, calls)
|
|
items.extend(assistant_items)
|
|
skipped_reasoning += skipped
|
|
continue
|
|
if record_type == "user":
|
|
items.extend(_user_items(record, calls, completed_calls))
|
|
elif record_type == "attachment":
|
|
attachment_item = _attachment_item(record)
|
|
if attachment_item is not None:
|
|
items.append(attachment_item)
|
|
elif record_type not in {"system"}:
|
|
raise HandoffError(f"Unsupported model-visible Claude record {record_type!r} at {record.get('uuid')}.")
|
|
index += 1
|
|
|
|
unfinished = sorted(set(calls) - completed_calls)
|
|
if unfinished:
|
|
joined = ", ".join(unfinished[:5])
|
|
raise HandoffError(
|
|
f"Claude's active state ends with unfinished tool call(s): {joined}. "
|
|
"Finish or stop the Claude turn before transferring it."
|
|
)
|
|
if not items:
|
|
raise HandoffError("Claude's active state produced no Codex history items.")
|
|
return items, skipped_reasoning
|
|
|
|
|
|
def _without_image_payloads(value: Any) -> Any:
|
|
if isinstance(value, list):
|
|
return [_without_image_payloads(item) for item in value]
|
|
if not isinstance(value, dict):
|
|
return value
|
|
|
|
cleaned = {key: _without_image_payloads(item) for key, item in value.items()}
|
|
if cleaned.get("type") == "input_image" and isinstance(cleaned.get("image_url"), str):
|
|
cleaned["image_url"] = "[Image saved locally during handoff]"
|
|
if cleaned.get("type") == "image" and isinstance(cleaned.get("source"), dict):
|
|
source = dict(cleaned["source"])
|
|
if source.get("type") == "base64" and "data" in source:
|
|
source["data"] = "[Image saved locally during handoff]"
|
|
cleaned["source"] = source
|
|
return cleaned
|
|
|
|
|
|
def _token_count(value: Any) -> int:
|
|
text = json.dumps(_without_image_payloads(value), ensure_ascii=False, separators=(",", ":"))
|
|
try:
|
|
import tiktoken
|
|
|
|
return len(tiktoken.get_encoding("o200k_base").encode(text))
|
|
except ImportError:
|
|
return (len(text) + 3) // 4
|
|
|
|
|
|
def build_plan(session: str, projects_dir: Path) -> HandoffPlan:
|
|
path = _resolve_session(session, projects_dir)
|
|
records, sha256 = _stable_jsonl(path)
|
|
chain = _active_chain(records)
|
|
imported, compact_uuid = _after_latest_compaction(chain)
|
|
imported = _merge_parallel_tool_results(imported, records)
|
|
items, skipped_reasoning = _responses_items(imported)
|
|
|
|
session_id = next(
|
|
(str(record["sessionId"]) for record in reversed(records) if record.get("sessionId")),
|
|
path.stem,
|
|
)
|
|
title = next(
|
|
(
|
|
str(record["customTitle"])
|
|
for record in reversed(records)
|
|
if record.get("type") == "custom-title" and record.get("customTitle")
|
|
),
|
|
f"Claude session {session_id[:8]}",
|
|
)
|
|
cwd = next(
|
|
(str(record["cwd"]) for record in chain if record.get("cwd")),
|
|
"",
|
|
)
|
|
if not cwd:
|
|
raise HandoffError("Claude session does not record its working directory.")
|
|
|
|
warnings: list[str] = []
|
|
if skipped_reasoning:
|
|
warnings.append(f"Skipped {skipped_reasoning} Claude hidden-reasoning block(s); they are not portable.")
|
|
|
|
source = SourceInfo(
|
|
path=str(path),
|
|
sha256=sha256,
|
|
session_id=session_id,
|
|
title=title,
|
|
cwd=str(Path(cwd).resolve()),
|
|
leaf_uuid=chain[-1]["uuid"],
|
|
compact_boundary_uuid=compact_uuid,
|
|
first_imported_uuid=imported[0]["uuid"],
|
|
last_imported_uuid=imported[-1]["uuid"],
|
|
codex_cwd=_git_root(Path(cwd)),
|
|
)
|
|
return HandoffPlan(
|
|
source=source,
|
|
items=items,
|
|
source_records=len(records),
|
|
active_records=len(chain),
|
|
imported_records=len(imported),
|
|
hidden_reasoning_blocks_skipped=skipped_reasoning,
|
|
approximate_tokens=_token_count(items),
|
|
warnings=warnings,
|
|
)
|
|
|
|
|
|
def _write_private(path: Path, body: str) -> None:
|
|
path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
|
|
try:
|
|
with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
|
|
stream.write(body)
|
|
os.replace(temporary, path)
|
|
finally:
|
|
Path(temporary).unlink(missing_ok=True)
|
|
|
|
|
|
def write_bundle(plan: HandoffPlan, path: Path) -> Path:
|
|
path = path.expanduser().resolve()
|
|
_write_private(path, json.dumps(plan.bundle(), ensure_ascii=False))
|
|
return path
|
|
|
|
|
|
def _validate_items(items: Any) -> None:
|
|
if not isinstance(items, list) or not items:
|
|
raise HandoffError("Handoff bundle contains no history items.")
|
|
calls: dict[str, str] = {}
|
|
completed: set[str] = set()
|
|
saw_user = False
|
|
for item in items:
|
|
if not isinstance(item, dict):
|
|
raise HandoffError("Invalid handoff history item.")
|
|
kind = item.get("type")
|
|
status = item.get("status")
|
|
if (
|
|
not isinstance(kind, str)
|
|
or (status is not None and not isinstance(status, str))
|
|
or status in {"incomplete", "in_progress"}
|
|
):
|
|
raise HandoffError("Invalid or incomplete handoff history item.")
|
|
if kind == "message":
|
|
role = item.get("role")
|
|
parts = item.get("content")
|
|
if (
|
|
not isinstance(role, str)
|
|
or role not in {"user", "assistant"}
|
|
or not isinstance(parts, list)
|
|
or not parts
|
|
):
|
|
raise HandoffError("Invalid handoff message role or content.")
|
|
saw_user = saw_user or role == "user"
|
|
for part in parts:
|
|
if not isinstance(part, dict) or not isinstance(part.get("type"), str):
|
|
raise HandoffError("Invalid handoff message part.")
|
|
if part.get("type") in {"input_text", "output_text"} and isinstance(part.get("text"), str):
|
|
continue
|
|
if part.get("type") == "input_image":
|
|
_, encoded = _data_url_payload(part.get("image_url"), "Handoff image")
|
|
try:
|
|
if not base64.b64decode(encoded, validate=True):
|
|
raise ValueError("empty image")
|
|
except (ValueError, binascii.Error) as exc:
|
|
raise HandoffError("Invalid handoff image data.") from exc
|
|
continue
|
|
raise HandoffError("Unsupported handoff message part.")
|
|
elif kind == "function_call":
|
|
call_id, name, arguments = item.get("call_id"), item.get("name"), item.get("arguments")
|
|
if not isinstance(call_id, str) or not call_id or not isinstance(name, str) or not name:
|
|
raise HandoffError("Invalid handoff tool call ID or name.")
|
|
if call_id in calls or not isinstance(arguments, str):
|
|
raise HandoffError("Duplicate or invalid handoff tool call.")
|
|
try:
|
|
json.loads(arguments)
|
|
except json.JSONDecodeError as exc:
|
|
raise HandoffError("Handoff tool arguments are not JSON.") from exc
|
|
calls[call_id] = name
|
|
elif kind == "function_call_output":
|
|
call_id = item.get("call_id")
|
|
if not isinstance(call_id, str) or call_id not in calls or call_id in completed:
|
|
raise HandoffError("Unmatched or duplicate handoff tool result.")
|
|
if "output" not in item:
|
|
raise HandoffError("Handoff tool result has no output.")
|
|
completed.add(call_id)
|
|
item.setdefault("name", calls[call_id])
|
|
else:
|
|
raise HandoffError(f"Unsupported handoff item type: {kind!r}.")
|
|
if set(calls) != completed:
|
|
raise HandoffError("Session has unfinished tool calls; finish or stop the source turn before handoff.")
|
|
if not saw_user:
|
|
raise HandoffError("Handoff contains no user message.")
|
|
|
|
|
|
def plan_from_bundle(payload: Any) -> HandoffPlan:
|
|
formats = {FORMAT_VERSION, "mem0.claude-to-codex.v1", "memo.claude-to-codex.v1"}
|
|
if not isinstance(payload, dict) or not isinstance(payload.get("format"), str) or payload["format"] not in formats:
|
|
raise HandoffError("Unsupported handoff bundle format.")
|
|
source_payload = payload.get("source")
|
|
items = payload.get("items")
|
|
warnings = payload.get("warnings", [])
|
|
if not isinstance(source_payload, dict) or not isinstance(warnings, list):
|
|
raise HandoffError("Handoff bundle has no source or has invalid warnings.")
|
|
_validate_items(items)
|
|
try:
|
|
fields = dict(source_payload)
|
|
legacy = payload["format"] != FORMAT_VERSION
|
|
fields.setdefault("host", "claude-code" if legacy else "")
|
|
for key in ("host", "session_id", "title", "cwd"):
|
|
if not isinstance(fields.get(key), str) or not fields[key].strip():
|
|
raise ValueError(f"invalid source field: {key}")
|
|
if not re.fullmatch(r"[a-z][a-z0-9-]*", fields["host"]):
|
|
raise ValueError("invalid source host")
|
|
fields.setdefault("path", f"{fields['host']}:{fields['session_id']}")
|
|
fields.setdefault("sha256", hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest())
|
|
fields.setdefault("leaf_uuid", str(len(items)))
|
|
fields.setdefault("first_imported_uuid", "1")
|
|
fields.setdefault("last_imported_uuid", str(len(items)))
|
|
fields.setdefault("compact_boundary_uuid", None)
|
|
source = SourceInfo(**fields)
|
|
for key, value in asdict(source).items():
|
|
if value is None and key in {"codex_cwd", "compact_boundary_uuid"}:
|
|
continue
|
|
if not isinstance(value, str):
|
|
raise ValueError(f"invalid source field: {key}")
|
|
if not re.fullmatch(r"[0-9a-f]{64}", source.sha256):
|
|
raise ValueError("invalid source digest")
|
|
counts = payload.get("counts", {})
|
|
return HandoffPlan(
|
|
source=source,
|
|
items=items,
|
|
source_records=int(counts.get("source_records", len(items))),
|
|
active_records=int(counts.get("active_records", len(items))),
|
|
imported_records=int(counts.get("imported_records", len(items))),
|
|
hidden_reasoning_blocks_skipped=int(counts.get("hidden_reasoning_blocks_skipped", 0)),
|
|
approximate_tokens=_token_count(items),
|
|
warnings=[str(warning) for warning in warnings],
|
|
)
|
|
except (KeyError, TypeError, ValueError, AttributeError) as exc:
|
|
raise HandoffError("Handoff bundle is incomplete or has invalid source fields.") from exc
|
|
|
|
|
|
def load_bundle(path: Path) -> HandoffPlan:
|
|
try:
|
|
text = sys.stdin.read() if str(path) == "-" else path.expanduser().resolve().read_text(encoding="utf-8")
|
|
return plan_from_bundle(json.loads(text))
|
|
except json.JSONDecodeError as exc:
|
|
raise HandoffError(f"Invalid handoff bundle JSON: {path}") from exc
|
|
|
|
|
|
def _git_root(cwd: Path) -> str | None:
|
|
completed = subprocess.run(
|
|
["git", "-C", str(cwd), "rev-parse", "--show-toplevel"],
|
|
text=True,
|
|
stdout=subprocess.PIPE,
|
|
stderr=subprocess.DEVNULL,
|
|
check=False,
|
|
)
|
|
if completed.returncode != 0:
|
|
return None
|
|
root = Path(completed.stdout.strip()).resolve()
|
|
return str(root) if root.is_dir() else None
|
|
|
|
|
|
def _with_cwd(plan: HandoffPlan, cwd: Path | None) -> HandoffPlan:
|
|
source_cwd = Path(plan.source.cwd).expanduser().resolve()
|
|
target = (
|
|
cwd.expanduser().resolve()
|
|
if cwd
|
|
else Path(plan.source.codex_cwd).expanduser().resolve()
|
|
if plan.source.codex_cwd
|
|
else Path(_git_root(source_cwd) or source_cwd)
|
|
)
|
|
if not target.is_dir():
|
|
raise HandoffError(f"Codex working directory does not exist: {target}")
|
|
return replace(plan, source=replace(plan.source, cwd=str(source_cwd), codex_cwd=str(target)))
|
|
|
|
|
|
def _codex_cwd(plan: HandoffPlan) -> str:
|
|
return plan.source.codex_cwd or plan.source.cwd
|
|
|
|
|
|
def _default_bundle_path(plan: HandoffPlan) -> Path:
|
|
session = re.sub(r"[^A-Za-z0-9._-]+", "-", plan.source.session_id).strip(".-")[:80] or "session"
|
|
name = f"{session}-{plan.source.sha256[:12]}.json"
|
|
return DEFAULT_BUNDLE_DIR / name
|
|
|
|
|
|
def _codex_context_limits(codex_home: Path) -> CodexContextLimits:
|
|
try:
|
|
import tomllib
|
|
except ImportError as exc:
|
|
raise HandoffError("Creating a Codex task requires Python 3.11 or newer; rerun with python3.11.") from exc
|
|
|
|
codex_home = codex_home.expanduser().resolve()
|
|
config_path = codex_home / "config.toml"
|
|
cache_path = codex_home / "models_cache.json"
|
|
try:
|
|
config = tomllib.loads(config_path.read_text(encoding="utf-8"))
|
|
except (OSError, tomllib.TOMLDecodeError) as exc:
|
|
raise HandoffError(f"Cannot read Codex configuration at {config_path}: {exc}") from exc
|
|
try:
|
|
cache = json.loads(cache_path.read_text(encoding="utf-8"))
|
|
except (OSError, json.JSONDecodeError) as exc:
|
|
raise HandoffError(f"Cannot read Codex model metadata at {cache_path}: {exc}") from exc
|
|
|
|
model = str(config.get("model") or "")
|
|
models = cache.get("models") if isinstance(cache, dict) else None
|
|
if not isinstance(models, list):
|
|
raise HandoffError(f"Codex model metadata has no model list: {cache_path}")
|
|
model_info = next(
|
|
(
|
|
item
|
|
for item in models
|
|
if isinstance(item, dict)
|
|
and (
|
|
item.get("slug") == model
|
|
or item.get("model") == model
|
|
or (not model and item.get("is_default") is True)
|
|
)
|
|
),
|
|
None,
|
|
)
|
|
if not isinstance(model_info, dict):
|
|
raise HandoffError(f"Codex model {model!r} is missing from {cache_path}; refresh Codex's model list.")
|
|
model = str(model_info.get("slug") or model_info.get("model") or model)
|
|
|
|
cached_context = model_info.get("context_window")
|
|
cached_max = model_info.get("max_context_window") or cached_context
|
|
if not isinstance(cached_context, int) or not isinstance(cached_max, int):
|
|
raise HandoffError(f"Codex model {model!r} does not report its context limits.")
|
|
configured_context = config.get("model_context_window")
|
|
context_window = min(configured_context, cached_max) if isinstance(configured_context, int) else cached_context
|
|
effective_percent = model_info.get("effective_context_window_percent", 95)
|
|
if not isinstance(effective_percent, int) or not 1 <= effective_percent <= 100:
|
|
raise HandoffError(f"Codex model {model!r} reports an invalid effective context percentage.")
|
|
|
|
context_auto_limit = context_window * 9 // 10
|
|
configured_auto_limit = config.get("model_auto_compact_token_limit")
|
|
auto_compact_limit = (
|
|
min(configured_auto_limit, context_auto_limit) if isinstance(configured_auto_limit, int) else context_auto_limit
|
|
)
|
|
return CodexContextLimits(
|
|
model=model,
|
|
context_window=context_window,
|
|
usable_context_window=context_window * effective_percent // 100,
|
|
auto_compact_token_limit=auto_compact_limit,
|
|
max_context_window=cached_max,
|
|
max_usable_context_window=cached_max * effective_percent // 100,
|
|
max_auto_compact_token_limit=cached_max * 9 // 10,
|
|
)
|
|
|
|
|
|
class CodexAppServer:
|
|
"""Small JSON-RPC client for a one-off local Codex app-server process."""
|
|
|
|
def __init__(
|
|
self,
|
|
codex_bin: str = "codex",
|
|
context_window_override: int | None = None,
|
|
codex_home: Path = DEFAULT_CODEX_HOME,
|
|
) -> None:
|
|
resolved = shutil.which(codex_bin)
|
|
if not resolved:
|
|
raise HandoffError(f"Codex executable not found: {codex_bin}")
|
|
command = [resolved]
|
|
if context_window_override is not None:
|
|
command.extend(["-c", f"model_context_window={context_window_override}"])
|
|
command.extend(["app-server", "--stdio"])
|
|
self.process = subprocess.Popen(
|
|
command,
|
|
stdin=subprocess.PIPE,
|
|
stdout=subprocess.PIPE,
|
|
stderr=subprocess.PIPE,
|
|
text=True,
|
|
bufsize=1,
|
|
env={**os.environ, "CODEX_HOME": str(codex_home.expanduser().resolve())},
|
|
)
|
|
self._responses: queue.Queue[dict[str, Any]] = queue.Queue()
|
|
self._notifications: queue.Queue[dict[str, Any]] = queue.Queue()
|
|
self._stderr: list[str] = []
|
|
self._next_id = 1
|
|
threading.Thread(target=self._read_stdout, daemon=True).start()
|
|
threading.Thread(target=self._read_stderr, daemon=True).start()
|
|
try:
|
|
self.request(
|
|
"initialize",
|
|
{
|
|
"clientInfo": {
|
|
"name": "mem0_session_handoff",
|
|
"title": "Mem0 local session handoff",
|
|
"version": "0.1.0",
|
|
}
|
|
},
|
|
)
|
|
self.notify("initialized", {})
|
|
except Exception:
|
|
self.close()
|
|
raise
|
|
|
|
def _read_stdout(self) -> None:
|
|
assert self.process.stdout is not None
|
|
for line in self.process.stdout:
|
|
try:
|
|
message = json.loads(line)
|
|
except json.JSONDecodeError:
|
|
continue
|
|
if not isinstance(message, dict):
|
|
continue
|
|
if "id" in message:
|
|
self._responses.put(message)
|
|
elif "method" in message:
|
|
self._notifications.put(message)
|
|
|
|
def _read_stderr(self) -> None:
|
|
assert self.process.stderr is not None
|
|
for line in self.process.stderr:
|
|
self._stderr.append(line.rstrip())
|
|
|
|
def _send(self, payload: dict[str, Any]) -> None:
|
|
if self.process.poll() is not None:
|
|
error = "\n".join(self._stderr[-20:])
|
|
raise HandoffError(f"Codex app-server stopped unexpectedly.\n{error}")
|
|
assert self.process.stdin is not None
|
|
self.process.stdin.write(json.dumps(payload, separators=(",", ":")) + "\n")
|
|
self.process.stdin.flush()
|
|
|
|
def request(self, method: str, params: dict[str, Any], timeout: float = 30) -> Any:
|
|
request_id = self._next_id
|
|
self._next_id += 1
|
|
self._send({"method": method, "id": request_id, "params": params})
|
|
deadline = time.monotonic() + timeout
|
|
deferred: list[dict[str, Any]] = []
|
|
try:
|
|
while True:
|
|
remaining = deadline - time.monotonic()
|
|
if remaining <= 0:
|
|
raise HandoffError(f"Codex app-server timed out on {method}.")
|
|
try:
|
|
response = self._responses.get(timeout=remaining)
|
|
except queue.Empty as exc:
|
|
raise HandoffError(f"Codex app-server timed out on {method}.") from exc
|
|
if response.get("id") != request_id:
|
|
deferred.append(response)
|
|
continue
|
|
if "error" in response:
|
|
raise HandoffError(f"Codex {method} failed: {response['error']}")
|
|
return response.get("result")
|
|
finally:
|
|
for response in deferred:
|
|
self._responses.put(response)
|
|
|
|
def notify(self, method: str, params: dict[str, Any]) -> None:
|
|
self._send({"method": method, "params": params})
|
|
|
|
def wait_for_notification(
|
|
self,
|
|
method: str,
|
|
predicate: Any | None = None,
|
|
timeout: float = 600,
|
|
) -> dict[str, Any]:
|
|
deadline = time.monotonic() + timeout
|
|
deferred: list[dict[str, Any]] = []
|
|
try:
|
|
while True:
|
|
remaining = deadline - time.monotonic()
|
|
if remaining <= 0:
|
|
raise HandoffError(f"Codex app-server timed out waiting for {method}.")
|
|
try:
|
|
notification = self._notifications.get(timeout=remaining)
|
|
except queue.Empty as exc:
|
|
raise HandoffError(f"Codex app-server timed out waiting for {method}.") from exc
|
|
if notification.get("method") != method:
|
|
deferred.append(notification)
|
|
continue
|
|
params = notification.get("params")
|
|
if predicate is None or predicate(params):
|
|
return notification
|
|
deferred.append(notification)
|
|
finally:
|
|
for notification in deferred:
|
|
self._notifications.put(notification)
|
|
|
|
def wait_for_any_notification(
|
|
self,
|
|
methods: set[str],
|
|
predicate: Any | None = None,
|
|
timeout: float = 600,
|
|
) -> dict[str, Any]:
|
|
deadline = time.monotonic() + timeout
|
|
deferred: list[dict[str, Any]] = []
|
|
try:
|
|
while True:
|
|
remaining = deadline - time.monotonic()
|
|
if remaining <= 0:
|
|
joined = ", ".join(sorted(methods))
|
|
raise HandoffError(f"Codex app-server timed out waiting for one of: {joined}.")
|
|
try:
|
|
notification = self._notifications.get(timeout=remaining)
|
|
except queue.Empty as exc:
|
|
joined = ", ".join(sorted(methods))
|
|
raise HandoffError(f"Codex app-server timed out waiting for one of: {joined}.") from exc
|
|
if notification.get("method") not in methods:
|
|
deferred.append(notification)
|
|
continue
|
|
params = notification.get("params")
|
|
if predicate is None or predicate(params):
|
|
return notification
|
|
deferred.append(notification)
|
|
finally:
|
|
for notification in deferred:
|
|
self._notifications.put(notification)
|
|
|
|
def close(self) -> None:
|
|
if self.process.poll() is None:
|
|
self.process.terminate()
|
|
try:
|
|
self.process.wait(timeout=5)
|
|
except subprocess.TimeoutExpired:
|
|
self.process.kill()
|
|
self.process.wait(timeout=5)
|
|
|
|
def __enter__(self) -> "CodexAppServer":
|
|
return self
|
|
|
|
def __exit__(self, *_: Any) -> None:
|
|
self.close()
|
|
|
|
|
|
def _item_text(item: dict[str, Any], asset_dir: Path) -> tuple[str, str]:
|
|
"""Convert one Responses item to a complete visible import message."""
|
|
item_type = item.get("type")
|
|
if item_type == "message":
|
|
role = str(item.get("role") or "")
|
|
if role not in {"user", "assistant"}:
|
|
raise HandoffError(f"Codex's session importer cannot represent role {role!r}.")
|
|
parts: list[str] = []
|
|
for part in item.get("content") or []:
|
|
if not isinstance(part, dict):
|
|
raise HandoffError("A handoff message contains an invalid content item.")
|
|
part_type = part.get("type")
|
|
if part_type in {"input_text", "output_text"}:
|
|
parts.append(str(part.get("text") or ""))
|
|
elif part_type == "input_image":
|
|
media_type, encoded = _data_url_payload(part.get("image_url"), "A Claude message image")
|
|
parts.append(_image_reference(media_type, encoded, asset_dir, "A Claude message image"))
|
|
else:
|
|
raise HandoffError(f"Codex's session importer cannot represent content type {part_type!r}.")
|
|
text = "\n\n".join(part for part in parts if part)
|
|
if not text:
|
|
raise HandoffError("A handoff message contains no transferable text.")
|
|
return role, text
|
|
|
|
if item_type == "function_call":
|
|
name = html.escape(str(item.get("name") or "unknown"), quote=True)
|
|
call_id = html.escape(str(item.get("call_id") or "unknown"), quote=True)
|
|
arguments = str(item.get("arguments") or "{}")
|
|
return (
|
|
"assistant",
|
|
f'<tool_call name="{name}" id="{call_id}">\n{arguments}\n</tool_call>',
|
|
)
|
|
|
|
if item_type == "function_call_output":
|
|
name = html.escape(str(item.get("name") or "unknown"), quote=True)
|
|
call_id = html.escape(str(item.get("call_id") or "unknown"), quote=True)
|
|
output = _tool_result_text(item.get("output"), asset_dir, f"Claude tool result {call_id}")
|
|
return (
|
|
"assistant",
|
|
f'<tool_result name="{name}" id="{call_id}">\n{output}\n</tool_result>',
|
|
)
|
|
|
|
raise HandoffError(f"Codex's session importer cannot represent item type {item_type!r}.")
|
|
|
|
|
|
def _native_import_records(plan: HandoffPlan, asset_dir: Path) -> list[dict[str, Any]]:
|
|
"""Build the Claude-shaped history consumed by Codex's native importer."""
|
|
cwd = _codex_cwd(plan)
|
|
records: list[dict[str, Any]] = [
|
|
{
|
|
"type": "custom-title",
|
|
"customTitle": plan.source.title,
|
|
"sessionId": plan.source.session_id,
|
|
}
|
|
]
|
|
saw_user = False
|
|
for index, item in enumerate(plan.items, 1):
|
|
role, text = _item_text(item, asset_dir)
|
|
saw_user = saw_user or role == "user"
|
|
records.append(
|
|
{
|
|
"type": role,
|
|
"sessionId": plan.source.session_id,
|
|
"uuid": f"mem0-handoff-{index}",
|
|
"cwd": cwd,
|
|
"isSidechain": False,
|
|
"message": {"role": role, "content": text},
|
|
}
|
|
)
|
|
if not saw_user:
|
|
raise HandoffError("The active Claude context contains no user message.")
|
|
return records
|
|
|
|
|
|
def _native_import_path(plan: HandoffPlan, claude_projects_dir: Path) -> Path:
|
|
source_key = hashlib.sha256(plan.source.path.encode("utf-8")).hexdigest()[:24]
|
|
safe_session = re.sub(r"[^A-Za-z0-9._-]+", "-", plan.source.session_id).strip("-")
|
|
safe_session = safe_session[:80] or source_key
|
|
return claude_projects_dir.expanduser().resolve() / ".mem0-handoffs" / f"{safe_session}-{source_key}.jsonl"
|
|
|
|
|
|
def _write_native_import(plan: HandoffPlan, path: Path, asset_dir: Path) -> str:
|
|
path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
body = "".join(
|
|
json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
|
|
for record in _native_import_records(plan, asset_dir)
|
|
)
|
|
_write_private(path, body)
|
|
return hashlib.sha256(body.encode("utf-8")).hexdigest()
|
|
|
|
|
|
def _native_import_params(source_path: Path, cwd: str) -> dict[str, Any]:
|
|
return {
|
|
"migrationItems": [
|
|
{
|
|
"itemType": "SESSIONS",
|
|
"description": f"Transfer Claude session {source_path.name}",
|
|
"cwd": None,
|
|
"details": {
|
|
"plugins": [],
|
|
"sessions": [{"path": str(source_path), "cwd": cwd, "title": None}],
|
|
"mcpServers": [],
|
|
"hooks": [],
|
|
"subagents": [],
|
|
"commands": [],
|
|
},
|
|
}
|
|
]
|
|
}
|
|
|
|
|
|
def _thread_id_from_completion(params: Any, source_path: Path) -> str | None:
|
|
if not isinstance(params, dict):
|
|
return None
|
|
canonical = str(source_path.resolve())
|
|
for result in params.get("itemTypeResults") or []:
|
|
if not isinstance(result, dict) or result.get("itemType") != "SESSIONS":
|
|
continue
|
|
for success in result.get("successes") or []:
|
|
if not isinstance(success, dict):
|
|
continue
|
|
if success.get("source") in {None, canonical} and success.get("target"):
|
|
return str(success["target"])
|
|
return None
|
|
|
|
|
|
def _thread_id_from_ledger(codex_home: Path, source_path: Path, content_sha256: str) -> str | None:
|
|
ledger_path = codex_home.expanduser() / "external_agent_session_imports.json"
|
|
if not ledger_path.is_file():
|
|
return None
|
|
try:
|
|
ledger = json.loads(ledger_path.read_text(encoding="utf-8"))
|
|
except json.JSONDecodeError:
|
|
return None
|
|
canonical = str(source_path.resolve())
|
|
matches = [
|
|
record
|
|
for record in ledger.get("records", [])
|
|
if isinstance(record, dict)
|
|
and record.get("source_path") == canonical
|
|
and record.get("content_sha256") == content_sha256
|
|
and record.get("imported_thread_id")
|
|
]
|
|
return str(matches[-1]["imported_thread_id"]) if matches else None
|
|
|
|
|
|
def _notification_thread_id(params: Any) -> str | None:
|
|
if not isinstance(params, dict):
|
|
return None
|
|
if params.get("threadId"):
|
|
return str(params["threadId"])
|
|
turn = params.get("turn")
|
|
if isinstance(turn, dict) and turn.get("threadId"):
|
|
return str(turn["threadId"])
|
|
return None
|
|
|
|
|
|
def _compact_imported_thread(
|
|
server: CodexAppServer,
|
|
thread_id: str,
|
|
) -> dict[str, Any] | None:
|
|
server.request("thread/resume", {"threadId": thread_id}, timeout=120)
|
|
server.request("thread/compact/start", {"threadId": thread_id}, timeout=30)
|
|
|
|
latest_usage: dict[str, Any] | None = None
|
|
saw_compaction_item = False
|
|
while True:
|
|
notification = server.wait_for_any_notification(
|
|
{"item/completed", "thread/tokenUsage/updated", "turn/completed", "error"},
|
|
lambda params: _notification_thread_id(params) in {None, thread_id},
|
|
timeout=600,
|
|
)
|
|
method = notification.get("method")
|
|
params = notification.get("params")
|
|
if method == "thread/tokenUsage/updated" and isinstance(params, dict):
|
|
token_usage = params.get("tokenUsage")
|
|
if isinstance(token_usage, dict):
|
|
latest_usage = token_usage
|
|
continue
|
|
if method == "item/completed" and isinstance(params, dict):
|
|
item = params.get("item")
|
|
if isinstance(item, dict) and item.get("type") == "contextCompaction":
|
|
saw_compaction_item = True
|
|
continue
|
|
if method == "error":
|
|
error = params.get("error") if isinstance(params, dict) else params
|
|
raise HandoffError(f"Codex could not compact the imported task: {error}")
|
|
if method == "turn/completed" and isinstance(params, dict):
|
|
turn = params.get("turn")
|
|
if not isinstance(turn, dict):
|
|
raise HandoffError("Codex returned an invalid compaction result.")
|
|
if turn.get("status") != "completed":
|
|
error = turn.get("error") or turn.get("status")
|
|
raise HandoffError(f"Codex could not compact the imported task: {error}")
|
|
if not saw_compaction_item:
|
|
raise HandoffError("Codex completed the compaction turn without a compaction item.")
|
|
return latest_usage
|
|
|
|
|
|
def _set_thread_name(
|
|
server: CodexAppServer,
|
|
thread_id: str,
|
|
name: str,
|
|
) -> None:
|
|
server.request(
|
|
"thread/name/set",
|
|
{"threadId": thread_id, "name": name},
|
|
timeout=30,
|
|
)
|
|
|
|
|
|
def create_codex_thread(
|
|
plan: HandoffPlan,
|
|
codex_bin: str = "codex",
|
|
codex_home: Path = DEFAULT_CODEX_HOME,
|
|
) -> dict[str, Any]:
|
|
limits = _codex_context_limits(codex_home)
|
|
should_compact = plan.approximate_tokens >= limits.auto_compact_token_limit
|
|
if should_compact and plan.approximate_tokens >= limits.max_auto_compact_token_limit:
|
|
raise HandoffError(
|
|
f"The active session state is approximately {plan.approximate_tokens:,} tokens. "
|
|
f"Codex cannot safely compact more than approximately "
|
|
f"{limits.max_auto_compact_token_limit:,} tokens in one request. "
|
|
"Compact in the source host and retry the handoff."
|
|
)
|
|
|
|
# Codex only imports sources staged under its native Claude home.
|
|
source_path = _native_import_path(plan, Path.home() / ".claude" / "projects")
|
|
safe_session = re.sub(r"[^A-Za-z0-9._-]+", "-", plan.source.session_id).strip("-")
|
|
asset_dir = (
|
|
codex_home.expanduser().resolve()
|
|
/ "external-agent-assets"
|
|
/ plan.source.host
|
|
/ (safe_session[:80] or "session")
|
|
)
|
|
content_sha256 = _write_native_import(plan, source_path, asset_dir)
|
|
try:
|
|
context_override = limits.max_context_window if should_compact else None
|
|
with CodexAppServer(codex_bin, context_override, codex_home=codex_home) as server:
|
|
response = server.request(
|
|
"externalAgentConfig/import",
|
|
_native_import_params(source_path, _codex_cwd(plan)),
|
|
timeout=120,
|
|
)
|
|
import_id = str((response or {}).get("importId") or "")
|
|
if not import_id:
|
|
raise HandoffError(f"Codex externalAgentConfig/import returned no import ID: {response!r}")
|
|
completed = server.wait_for_notification(
|
|
IMPORT_COMPLETED_NOTIFICATION,
|
|
lambda params: isinstance(params, dict) and params.get("importId") == import_id,
|
|
)
|
|
completed_params = completed.get("params")
|
|
thread_id = _thread_id_from_completion(completed_params, source_path)
|
|
if not thread_id:
|
|
thread_id = _thread_id_from_ledger(codex_home, source_path, content_sha256)
|
|
if not thread_id:
|
|
raise HandoffError(
|
|
"Codex finished importing the session but did not report the new task ID. "
|
|
f"Import result: {json.dumps(completed_params, ensure_ascii=False)}"
|
|
)
|
|
|
|
read = server.request(
|
|
"thread/read",
|
|
{"threadId": thread_id, "includeTurns": True},
|
|
)
|
|
thread = (read or {}).get("thread") if isinstance(read, dict) else None
|
|
if not isinstance(thread, dict):
|
|
raise HandoffError(f"Codex could not read imported task {thread_id}.")
|
|
turns = thread.get("turns") or []
|
|
preview = str(thread.get("preview") or "")
|
|
if not turns or not preview:
|
|
raise HandoffError(f"Codex imported task {thread_id}, but it has no visible history.")
|
|
|
|
compaction_usage = _compact_imported_thread(server, thread_id) if should_compact else None
|
|
_set_thread_name(server, thread_id, plan.source.title)
|
|
|
|
return {
|
|
"thread_id": thread_id,
|
|
"title": plan.source.title,
|
|
"cwd": _codex_cwd(plan),
|
|
"source_session_id": plan.source.session_id,
|
|
"source_host": plan.source.host,
|
|
"visible_turns": len(turns),
|
|
"preview": preview,
|
|
"responses_items_converted": len(plan.items),
|
|
"approximate_import_tokens": plan.approximate_tokens,
|
|
"target_model": limits.model,
|
|
"target_context_window": limits.context_window,
|
|
"target_usable_context_window": limits.usable_context_window,
|
|
"target_auto_compact_token_limit": limits.auto_compact_token_limit,
|
|
"compacted_before_return": should_compact,
|
|
"compaction_context_window": (limits.max_context_window if should_compact else None),
|
|
"compaction_token_usage": compaction_usage,
|
|
"model_invoked": should_compact,
|
|
}
|
|
finally:
|
|
source_path.unlink(missing_ok=True)
|
|
try:
|
|
source_path.parent.rmdir()
|
|
except OSError:
|
|
pass
|
|
|
|
|
|
def _summary(plan: HandoffPlan) -> dict[str, Any]:
|
|
return {
|
|
"source": plan.source.path,
|
|
"source_host": plan.source.host,
|
|
"session_id": plan.source.session_id,
|
|
"title": plan.source.title,
|
|
"source_cwd": plan.source.cwd,
|
|
"codex_cwd": _codex_cwd(plan),
|
|
"leaf_uuid": plan.source.leaf_uuid,
|
|
"compact_boundary_uuid": plan.source.compact_boundary_uuid,
|
|
"source_records": plan.source_records,
|
|
"active_records": plan.active_records,
|
|
"imported_records": plan.imported_records,
|
|
"responses_items": len(plan.items),
|
|
"approximate_import_tokens": plan.approximate_tokens,
|
|
"warnings": plan.warnings,
|
|
}
|
|
|
|
|
|
def _command_output(result: dict[str, Any]) -> str:
|
|
title = str(result["title"])
|
|
cwd = str(result["cwd"])
|
|
project = Path(cwd).name or cwd
|
|
lines = [
|
|
f'Created Codex task "{title}".',
|
|
f"Task ID: {result['thread_id']}",
|
|
f"Project: {project}",
|
|
]
|
|
if result.get("compacted_before_return"):
|
|
lines.append("Codex compacted the transferred context before opening the task.")
|
|
lines.append(f'Open Codex and select "{title}" under {project}.')
|
|
return "\n".join(lines)
|
|
|
|
|
|
def _parse_args(argv: Iterable[str] | None = None, default_source: str | None = "claude-code") -> argparse.Namespace:
|
|
parser = argparse.ArgumentParser(description=__doc__)
|
|
source = parser.add_mutually_exclusive_group(required=True)
|
|
source.add_argument("--session", help="Native session transcript path (Claude also accepts its session ID)")
|
|
parser.add_argument(
|
|
"--source",
|
|
choices=("claude-code", "cursor", "codex", "kimi", "antigravity", "openclaw", "pi-agent"),
|
|
default=default_source,
|
|
)
|
|
parser.add_argument("--title", help="Override the imported task title")
|
|
source.add_argument("--bundle", type=Path, help="Previously exported handoff bundle")
|
|
parser.add_argument(
|
|
"--claude-projects-dir",
|
|
type=Path,
|
|
default=Path.home() / ".claude" / "projects",
|
|
)
|
|
parser.add_argument("--export", type=Path, help="Write a private reusable handoff bundle")
|
|
parser.add_argument(
|
|
"--cwd",
|
|
type=Path,
|
|
help="Use this existing directory instead of the source session's directory",
|
|
)
|
|
parser.add_argument("--create", action="store_true", help="Create the Codex task")
|
|
parser.add_argument(
|
|
"--target",
|
|
choices=("codex",),
|
|
default="codex",
|
|
help="Destination coding agent",
|
|
)
|
|
parser.add_argument(
|
|
"--command-output",
|
|
action="store_true",
|
|
help="Print the short result used by Mem0's user-facing command",
|
|
)
|
|
parser.add_argument("--codex-bin", default="codex")
|
|
parser.add_argument(
|
|
"--codex-home",
|
|
type=Path,
|
|
default=DEFAULT_CODEX_HOME,
|
|
)
|
|
return parser.parse_args(argv)
|
|
|
|
|
|
def main(argv: Iterable[str] | None = None, default_source: str | None = "claude-code") -> int:
|
|
args = _parse_args(argv, default_source)
|
|
try:
|
|
if args.bundle:
|
|
plan = load_bundle(args.bundle)
|
|
elif args.source == "claude-code":
|
|
plan = build_plan(args.session, args.claude_projects_dir)
|
|
else:
|
|
if not args.source:
|
|
raise HandoffError("--source is required with --session.")
|
|
from handoff_sources import read_source
|
|
|
|
plan = read_source(args.source, Path(args.session), cwd=args.cwd, title=args.title)
|
|
if args.title:
|
|
plan = replace(plan, source=replace(plan.source, title=args.title))
|
|
plan = _with_cwd(plan, args.cwd)
|
|
output: dict[str, Any] = {"plan": _summary(plan)}
|
|
if args.export:
|
|
output["bundle"] = str(write_bundle(plan, args.export))
|
|
if args.create:
|
|
try:
|
|
output["codex"] = create_codex_thread(
|
|
plan,
|
|
codex_bin=args.codex_bin,
|
|
codex_home=args.codex_home.expanduser(),
|
|
)
|
|
except (HandoffError, OSError, subprocess.SubprocessError) as exc:
|
|
fallback = args.export or _default_bundle_path(plan)
|
|
saved = write_bundle(plan, fallback)
|
|
raise HandoffError(f"{exc} The complete handoff was saved at {saved}.") from exc
|
|
if args.command_output:
|
|
if not args.create:
|
|
raise HandoffError("--command-output requires --create.")
|
|
print(_command_output(output["codex"]))
|
|
else:
|
|
print(json.dumps(output, indent=2, ensure_ascii=False))
|
|
return 0
|
|
except (HandoffError, OSError, subprocess.SubprocessError) as exc:
|
|
print(f"handoff failed: {exc}", file=sys.stderr)
|
|
return 1
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|