Skip to content

Commit d0edde5

Browse files
committed
release: publish csep 1.3.8
1 parent d7ec032 commit d0edde5

11 files changed

Lines changed: 854 additions & 14 deletions

‎docs/2026-05-22-csep-memory-runtime-status.html‎

Lines changed: 465 additions & 0 deletions
Large diffs are not rendered by default.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "csep"
7-
version = "1.3.7"
7+
version = "1.3.8"
88
description = "Self-evolution loop for OpenAI Codex: session reflection, session recall, and reflection-generated skills with zero Python runtime dependencies."
99
readme = "README.md"
1010
requires-python = ">=3.11"
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
__all__ = ["__version__"]
22

3-
__version__ = "1.3.7"
3+
__version__ = "1.3.8"
Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,41 @@
1-
# Session Recall Pointer
1+
# CSEP Session Recall Policy
22

3-
For historical session search, use the `csep-session-recall` plugin skill.
4-
Treat `csep recall` like `rg` over past sessions: search short concrete needles, not long natural-language questions.
3+
<IMPORTANT>
4+
Before answering or taking action, check whether this task may depend on prior local session context.
5+
6+
If there is a reasonable chance that previous Codex or Claude Code sessions contain useful evidence, you MUST use the `csep-session-recall` plugin skill before proceeding.
7+
8+
Do not rely only on the stable background injected at startup. This policy does not install or rely on UserPromptSubmit automatic recall; the agent must actively choose the recall skill. When unsure, use recall.
9+
</IMPORTANT>
10+
11+
## Use Recall For
12+
13+
- today's, recent, previous, unfinished, or continued work
14+
- status, handoff, cleanup, wrap-up, or "what remains"
15+
- bugs, failures, repeated issues, regressions, logs, or test output
16+
- previous commands, branches, commits, reviews, hooks, skills, local tools, or config state
17+
- exact user wording from earlier conversations
18+
- anything mentioning `recall`, memory, session history, CSEP, hooks, or skills
19+
20+
Chinese trigger examples: `今天`, `最近`, `刚才`, `之前`, `上次`, `继续`, `接着`, `状态`, `运行状态`, `交接`, `收尾`, `还剩什么`, `又报错`, `怎么又`, `查一下`, `看看`, `本地`, `hook`, `skill`, `recall`.
21+
22+
## Skip Recall Only When
23+
24+
Skip recall only when one of these boundaries clearly applies:
25+
26+
- the task is clearly self-contained, such as translation, formatting, arithmetic, or a tiny edit with complete context
27+
- the user explicitly says not to use recall or not to check history
28+
29+
## Query Style
30+
31+
Treat `csep recall` like `rg` over past sessions. Extract 2-6 short concrete needles: file names, commands, errors, symbols, hook names, config keys, branch names, or exact user wording.
32+
33+
Prefer:
34+
35+
```bash
36+
csep recall "hooks.json|SessionStart|Recall Policy" --cwd "$PWD"
37+
csep recall "missing transcript_path|discovery_ambiguous" --cwd "$PWD"
38+
csep recall --recent --cwd "$PWD"
39+
```
40+
41+
Avoid long natural-language questions. Use recall results as evidence, not authority; current files, live command output, and explicit user instructions take precedence.

‎src/codex_self_evolution/session_recall/session_recall.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The runtime recall guide now lives in the CSEP plugin skill:
66
skills/csep-session-recall/SKILL.md
77
```
88

9-
`SessionStart` does not inject this file. It only injects stable background plus a short pointer to the plugin skill.
9+
`SessionStart` does not inject this file. It only injects stable background plus the compact recall policy from `policy.md`.
1010

1111
Use recall like `rg` over past sessions:
1212

‎src/codex_self_evolution/session_reflection/prompt.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ def build_reflection_prompt(
7070
"The frontmatter name must match the csep-reflect-* directory name.\n\n"
7171
"Write receipt.json atomically: write the JSON to a temporary file in the same directory, then rename it "
7272
"to the required receipt path.\n"
73+
"Do not use shell variables, placeholders, command substitution, or quoted shell expressions in receipt.json. "
74+
"The parent process will canonicalize job_id, parent_session_id, child_thread_id, started_at, and finished_at; "
75+
"your main responsibility is an accurate status plus memory_changes, skill_changes, skipped_candidates, "
76+
"validation_notes, and errors.\n"
7377
"Write receipt.json with this exact top-level shape:\n"
7478
"{\n"
7579
' "schema_version": 1,\n'

‎src/codex_self_evolution/session_reflection/runner.py‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
from __future__ import annotations
22

3+
import hashlib
34
import json
5+
import shutil
46
import time
57
from pathlib import Path
68
from typing import Any
@@ -144,6 +146,12 @@ def run_reflection_job(
144146
job_id=job_id,
145147
home=resolved_home,
146148
)
149+
receipt_started_at = utc_timestamp()
150+
output_snapshot = _snapshot_reflection_outputs(
151+
memory_dir=project_paths.memory_dir,
152+
skills_root=skills_root,
153+
skill_prefix=config.skill_prefix,
154+
)
147155
prompt = build_reflection_prompt(
148156
job_id=job_id,
149157
parent_session_id=str(job["parent_session_id"]),
@@ -168,6 +176,17 @@ def run_reflection_job(
168176
prompt=prompt,
169177
)
170178
_wait_for_receipt(paths.receipt_path, timeout_seconds=config.timeout_seconds)
179+
_prepare_receipt_for_validation(
180+
paths.receipt_path,
181+
before=output_snapshot,
182+
memory_dir=project_paths.memory_dir,
183+
skills_root=skills_root,
184+
skill_prefix=config.skill_prefix,
185+
job_id=job_id,
186+
parent_session_id=str(job["parent_session_id"]),
187+
child_thread_id=child_thread_id,
188+
started_at=receipt_started_at,
189+
)
171190

172191
validation = validate_receipt(
173192
paths.receipt_path,
@@ -288,6 +307,218 @@ def _receipt_text_is_parseable(text: str) -> bool:
288307
return False
289308

290309

310+
def _prepare_receipt_for_validation(
311+
receipt_path: Path,
312+
*,
313+
before: dict[str, dict[str, str]],
314+
memory_dir: Path,
315+
skills_root: Path,
316+
skill_prefix: str,
317+
job_id: str,
318+
parent_session_id: str,
319+
child_thread_id: str,
320+
started_at: str,
321+
) -> None:
322+
"""Canonicalize receipt envelope and recover valid durable writes when possible."""
323+
finished_at = utc_timestamp()
324+
raw_receipt, raw_error = _load_receipt_object(receipt_path)
325+
if isinstance(raw_receipt, dict):
326+
receipt = dict(raw_receipt)
327+
_canonicalize_receipt_envelope(
328+
receipt,
329+
job_id=job_id,
330+
parent_session_id=parent_session_id,
331+
child_thread_id=child_thread_id,
332+
started_at=started_at,
333+
finished_at=finished_at,
334+
)
335+
atomic_write_json(receipt_path, receipt)
336+
return
337+
338+
memory_changes, skill_changes = _changed_reflection_outputs(
339+
before,
340+
after=_snapshot_reflection_outputs(
341+
memory_dir=memory_dir,
342+
skills_root=skills_root,
343+
skill_prefix=skill_prefix,
344+
),
345+
memory_dir=memory_dir,
346+
)
347+
if not memory_changes and not skill_changes:
348+
return
349+
350+
invalid_path = _preserve_invalid_receipt(receipt_path)
351+
recovered_receipt: dict[str, Any] = {
352+
"schema_version": 1,
353+
"job_id": job_id,
354+
"parent_session_id": parent_session_id,
355+
"child_thread_id": child_thread_id,
356+
"status": "partial",
357+
"memory_changes": memory_changes,
358+
"skill_changes": skill_changes,
359+
"skipped_candidates": [],
360+
"validation_notes": [
361+
{
362+
"reason": "receipt_recovered_from_durable_outputs",
363+
"raw_receipt_error": raw_error,
364+
"raw_receipt_path": str(invalid_path) if invalid_path is not None else "",
365+
}
366+
],
367+
"errors": [],
368+
"started_at": started_at,
369+
"finished_at": finished_at,
370+
}
371+
atomic_write_json(receipt_path, recovered_receipt)
372+
373+
374+
def _load_receipt_object(receipt_path: Path) -> tuple[dict[str, Any] | None, str]:
375+
"""Return a parseable receipt object or a compact read/parse failure reason."""
376+
if not receipt_path.is_file():
377+
return None, "receipt_missing"
378+
try:
379+
text = receipt_path.read_text(encoding="utf-8")
380+
except OSError as exc:
381+
return None, f"receipt_unreadable: {exc}"
382+
if not text.strip():
383+
return None, "receipt_empty"
384+
try:
385+
loaded = json.loads(text)
386+
except ValueError as exc:
387+
return None, f"receipt_invalid_json: {exc}"
388+
if not isinstance(loaded, dict):
389+
return None, "receipt_not_object"
390+
return loaded, ""
391+
392+
393+
def _canonicalize_receipt_envelope(
394+
receipt: dict[str, Any],
395+
*,
396+
job_id: str,
397+
parent_session_id: str,
398+
child_thread_id: str,
399+
started_at: str,
400+
finished_at: str,
401+
) -> None:
402+
"""Replace deterministic receipt envelope fields with parent-owned values."""
403+
canonical_fields = {
404+
"schema_version": 1,
405+
"job_id": job_id,
406+
"parent_session_id": parent_session_id,
407+
"child_thread_id": child_thread_id,
408+
"started_at": started_at,
409+
"finished_at": finished_at,
410+
}
411+
changed_fields = [key for key, value in canonical_fields.items() if receipt.get(key) != value]
412+
receipt.update(canonical_fields)
413+
if changed_fields and isinstance(receipt.get("validation_notes"), list):
414+
receipt["validation_notes"].append(
415+
{
416+
"reason": "receipt_envelope_canonicalized",
417+
"fields": changed_fields,
418+
}
419+
)
420+
421+
422+
def _snapshot_reflection_outputs(
423+
*,
424+
memory_dir: Path,
425+
skills_root: Path,
426+
skill_prefix: str,
427+
) -> dict[str, dict[str, str]]:
428+
"""Return hashes for durable memory refs and active reflection skills."""
429+
snapshot: dict[str, dict[str, str]] = {}
430+
for path in _iter_reflection_output_files(memory_dir=memory_dir, skills_root=skills_root, skill_prefix=skill_prefix):
431+
if not path.is_file():
432+
continue
433+
snapshot[_snapshot_key(path)] = {
434+
"path": str(path),
435+
"hash": hashlib.sha256(path.read_bytes()).hexdigest(),
436+
}
437+
return snapshot
438+
439+
440+
def _iter_reflection_output_files(*, memory_dir: Path, skills_root: Path, skill_prefix: str) -> list[Path]:
441+
"""Return files the reflection worker is allowed to mutate durably."""
442+
files: list[Path] = []
443+
memory_file = memory_dir / "MEMORY.md"
444+
if memory_file.exists():
445+
files.append(memory_file)
446+
refs_dir = memory_dir / "refs"
447+
if refs_dir.is_dir():
448+
files.extend(sorted(path for path in refs_dir.glob("**/*.md") if path.is_file()))
449+
if skills_root.is_dir():
450+
for skill_dir in sorted(skills_root.iterdir()):
451+
if skill_dir.is_dir() and skill_dir.name.startswith(skill_prefix):
452+
skill_file = skill_dir / "SKILL.md"
453+
if skill_file.exists():
454+
files.append(skill_file)
455+
return files
456+
457+
458+
def _changed_reflection_outputs(
459+
before: dict[str, dict[str, str]],
460+
*,
461+
after: dict[str, dict[str, str]],
462+
memory_dir: Path,
463+
) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
464+
"""Return receipt change entries inferred from before/after output hashes."""
465+
memory_changes: list[dict[str, str]] = []
466+
skill_changes: list[dict[str, str]] = []
467+
for key in sorted(set(before) | set(after)):
468+
before_item = before.get(key)
469+
after_item = after.get(key)
470+
before_hash = before_item["hash"] if before_item is not None else ""
471+
after_hash = after_item["hash"] if after_item is not None else ""
472+
if before_hash == after_hash:
473+
continue
474+
path = Path((after_item or before_item or {}).get("path", ""))
475+
change = {
476+
"path": str(path),
477+
"action": _change_action(before_item, after_item),
478+
"before_hash": before_hash,
479+
"after_hash": after_hash,
480+
}
481+
if _is_memory_output(path, memory_dir):
482+
memory_changes.append(change)
483+
else:
484+
skill_changes.append(change)
485+
return memory_changes, skill_changes
486+
487+
488+
def _change_action(before_item: dict[str, str] | None, after_item: dict[str, str] | None) -> str:
489+
"""Return the action name for a before/after file snapshot pair."""
490+
if before_item is None:
491+
return "create"
492+
if after_item is None:
493+
return "delete"
494+
return "update"
495+
496+
497+
def _is_memory_output(path: Path, memory_dir: Path) -> bool:
498+
"""Return whether a changed durable output belongs to the memory root."""
499+
try:
500+
return path.expanduser().resolve(strict=False).is_relative_to(memory_dir.expanduser().resolve(strict=False))
501+
except OSError:
502+
return False
503+
504+
505+
def _snapshot_key(path: Path) -> str:
506+
"""Return a stable key for a local output file path."""
507+
return str(path.expanduser().resolve(strict=False))
508+
509+
510+
def _preserve_invalid_receipt(receipt_path: Path) -> Path | None:
511+
"""Move an invalid child receipt aside so the recovered receipt keeps evidence."""
512+
if not receipt_path.exists():
513+
return None
514+
invalid_path = receipt_path.with_name("receipt.invalid.txt")
515+
try:
516+
shutil.move(str(receipt_path), str(invalid_path))
517+
except OSError:
518+
return None
519+
return invalid_path
520+
521+
291522
def _archive_only_for_unavailable_app_server(
292523
decision: dict[str, Any],
293524
proxy_status: dict[str, Any],

‎src/codex_self_evolution/session_reflection/validation.py‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import hashlib
44
import json
55
import re
6+
from datetime import datetime
67
from pathlib import Path
78
from typing import Any
89

@@ -35,7 +36,10 @@ def validate_receipt(
3536
if not receipt_path.is_file():
3637
return _failure("receipt_missing")
3738
try:
38-
receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
39+
receipt_text = receipt_path.read_text(encoding="utf-8")
40+
if not receipt_text.strip():
41+
return _failure("receipt_empty")
42+
receipt = json.loads(receipt_text)
3943
except (OSError, ValueError) as exc:
4044
result = _failure("receipt_invalid_json")
4145
result["error"] = str(exc)
@@ -99,6 +103,9 @@ def _receipt_schema_reason(receipt: dict[str, Any]) -> str:
99103
for field in REQUIRED_TEXT_FIELDS:
100104
if not isinstance(receipt.get(field), str) or not receipt[field].strip():
101105
return "receipt_schema"
106+
for field in ("started_at", "finished_at"):
107+
if not _is_utc_iso_timestamp(str(receipt[field])):
108+
return "receipt_timestamp"
102109
if receipt.get("status") not in VALID_RECEIPT_STATUSES:
103110
return "receipt_status"
104111
for field in REQUIRED_LIST_FIELDS:
@@ -107,6 +114,17 @@ def _receipt_schema_reason(receipt: dict[str, Any]) -> str:
107114
return ""
108115

109116

117+
def _is_utc_iso_timestamp(value: str) -> bool:
118+
"""Return whether a receipt timestamp is a concrete UTC ISO timestamp."""
119+
if not value.endswith("Z") or "$" in value or "<" in value or ">" in value:
120+
return False
121+
try:
122+
datetime.fromisoformat(value.replace("Z", "+00:00"))
123+
except ValueError:
124+
return False
125+
return True
126+
127+
110128
def _receipt_identity_reason(
111129
receipt: dict[str, Any],
112130
*,

0 commit comments

Comments
 (0)