Skip to content

YujunZhou/tellonce / codex

tellonce

Verified

Use to view, explain, correct, delete or reorganize the user's saved preferences, or to record one by hand when automatic recording is off; learning and rule injection otherwise run automatically through Codex hooks.

FileKindSize
.codex-plugin/plugin.jsonconfig1.3 KB
SKILL.mdskill md12.0 KB
dashboard.shexecutablescript348 B
docs/CC_PARITY_MATRIX.mdmarkdown7.3 KB
docs/README.mdmarkdown3.4 KB
doctor.shexecutablescript345 B
hooks/hooks.jsonconfig714 B
hooks/posttooluse-deterministic-block.shexecutablescript2.0 KB
hooks/sessionstart-init.shexecutablescript1.9 KB
hooks/userpromptsubmit-dispatch.pyscript2.6 KB
hooks/userpromptsubmit-memory-upsert.shscript326 B
hooks/userpromptsubmit-pending-inject.shexecutablescript2.0 KB
hooks/userpromptsubmit-retrieve-inject.shexecutablescript3.1 KB
hooks/userpromptsubmit-shadow-alert-inject.shexecutablescript1.2 KB
install.shexecutablescript13.9 KB
shared_lib/_install_merge_settings.pyscript12.1 KB
shared_lib/_pt_hooks.txtmarkdown407 B
shared_lib/correction_interpretation.pyscript8.5 KB
shared_lib/detect_user_prefer.pyscript7.2 KB
shared_lib/deterministic_block.pyscript9.3 KB
shared_lib/event_obligations.pyscript19.8 KB
shared_lib/execution_support.pyscript75.8 KB
shared_lib/fingerprints.yamlconfig1.1 KB
shared_lib/learning_policy.pyscript4.6 KB
shared_lib/memory_judge.pyscript84.8 KB
shared_lib/memory_publication.pyscript14.9 KB
shared_lib/memory_runtime.pyscript12.2 KB
shared_lib/memory_store.pyscript99.6 KB
shared_lib/memory_upsert.pyscript57.1 KB
shared_lib/memory_upsert_hook.pyscript4.6 KB
shared_lib/model_requests.pyscript5.8 KB
shared_lib/path_config.pyscript13.3 KB
shared_lib/pending_queue_manager.pyscript23.4 KB
shared_lib/pt_platform.pyscript1.5 KB
shared_lib/redaction.pyscript3.4 KB
shared_lib/retrieve_inject.pyexecutablescript57.9 KB
shared_lib/rule_selection.pyscript18.9 KB
shared_lib/shadow_alert_inject.pyscript6.1 KB
shared_lib/training_memory.pyscript17.8 KB
shared_lib/transcript_adapter.pyscript13.7 KB
shared_lib/verify_compliance.pyexecutablescript24.5 KB
shared_lib/verify_retry_shadow.pyscript27.4 KB
tellonce_codex/__init__.pyscript52 B
tellonce_codex/__main__.pyscript49 B
tellonce_codex/cli.pyscript6.8 KB
tellonce_codex/codex_posttooluse_block.pyscript11.2 KB
tellonce_codex/dashboard.pyscript3.4 KB
tellonce_codex/doctor.pyscript10.9 KB
tellonce_codex/index.pyscript1.8 KB
tellonce_codex/install.pyscript3.1 KB
tellonce_codex/install_codex_hooks.pyscript15.1 KB
tellonce_codex/ledger.pyscript17.1 KB
tellonce_codex/memory.pyscript5.3 KB
tellonce_codex/migrate.pyscript1.3 KB
tellonce_codex/mode.pyscript2.3 KB
tellonce_codex/paths.pyscript8.6 KB
tellonce_codex/promote.pyscript4.4 KB
tellonce_codex/scan.pyscript2.6 KB
tellonce_codex/uninstall.pyscript1.7 KB
tellonce_codex/verify.pyscript5.3 KB
tellonce_codex/wrapper.pyscript12.0 KB
uninstall.shexecutablescript4.6 KB

shared_lib/training_memory.py

View on GitHub
"""Explicit experiment-owned learning, publication and freeze lifecycle.

Call process_pending in the owning background worker, never in the solver's
foreground prompt hook. This module does not launch processes or select models.
"""
from __future__ import annotations

import json
import sqlite3
import time
from pathlib import Path

from execution_support import SupportError, canonical, digest
from memory_publication import (Publication, _atomic_write, _read, _writer_lock,
                                load_publication, prepare_publication, publish, repair_publication)
from memory_store import DB_FILENAME, MemoryStore
import memory_upsert
from rule_selection import load_snapshot
from model_requests import bind_context, learning_recovery_delay


class _RecoveryRequests:
    """A persisted, one-time recovery has distinct bounded transport receipts."""
    def __init__(self, invoke, turn_key):
        self.invoke,self.turn_key=invoke,turn_key

    def __call__(self,prompt):
        raise SupportError('learning recovery needs a labelled durable request owner')

    def request_validated(self,prompt,*,role,validate,max_attempts=2,request_key=None):
        try:
            return self.invoke.request_validated(prompt,role=role,validate=validate,
                max_attempts=max_attempts,**({'request_key':request_key} if request_key is not None else {}))
        except Exception as exc:
            # Completed stages keep their original durable receipts. Only a
            # proven exhausted transient request may consume the recovery key.
            if learning_recovery_delay(exc) is None:
                raise
        key='learning-recovery-1:'+digest({'turn':self.turn_key,'role':role,
                                         'prompt':prompt,'key':request_key})
        return self.invoke.request_validated(prompt,role=role,validate=validate,
            max_attempts=max_attempts,request_key=key)


class _TrainingRequests:
    def __init__(self,memory):
        self.memory=memory

    def __call__(self,prompt):
        raise SupportError('background learning request is missing its persisted user-event origin')

    def for_turn(self,turn):
        memory=self.memory
        origin=json.loads(_read(memory._origin_path(turn['turn_key'])))
        context_keys={'namespace','phase','scope','task_id','session_id','event_id'}
        if (not isinstance(origin,dict) or set(origin)!=context_keys|{'schema','turn_key','source_digest','public_task_digest'} or
                type(origin['schema']) is not int or origin['schema']!=1 or origin['namespace']!=memory.namespace or origin['phase']!='training' or
                origin['scope']!='user_event' or origin['turn_key']!=turn['turn_key'] or
                origin['source_digest']!=digest(turn['source_text']) or
                not isinstance(origin['public_task_digest'],str) or len(origin['public_task_digest'])!=64 or
                any(c not in '0123456789abcdef' for c in origin['public_task_digest']) or
                origin['turn_key']!='experiment-'+digest({'task':origin['task_id'],'event':origin['event_id']})):
            raise SupportError('learning request origin differs from its owned queued user event')
        bound=bind_context(memory.invoke,{key:origin[key] for key in context_keys})
        receipt=MemoryStore(memory.root,legacy_dirs=[]).learning_recovery(turn['turn_key'])
        return _RecoveryRequests(bound,turn['turn_key']) if receipt and receipt['epoch']==1 else bound


class TrainingMemory:
    def __init__(self, root: Path, *, namespace: str, compiler_id: str, invoke):
        if not isinstance(root, Path) or not root.is_absolute() or root.is_symlink():
            raise SupportError('an explicit absolute experiment library is required')
        if not callable(invoke) or not isinstance(compiler_id, str) or not compiler_id:
            raise SupportError('explicit bounded model transport and compiler identity are required')
        # Opening never initializes, relabels, or imports an old library.
        load_snapshot(root, namespace=namespace)
        self.root = root
        self.namespace = namespace
        self.compiler_id = compiler_id
        self.invoke = invoke
        self.publications = root / 'published'
        ready = load_publication(self.publications, expected_namespace=namespace)
        if ready.compiler_id != compiler_id:
            raise SupportError('compiler configuration changed; use a new experiment identity')

    @classmethod
    def create(cls, root: Path, *, namespace: str, compiler_id: str, invoke):
        if not isinstance(root, Path) or not root.is_absolute() or root.is_symlink():
            raise SupportError('an explicit absolute fresh experiment directory is required')
        if (not isinstance(namespace, str) or not namespace.strip()
                or not isinstance(compiler_id, str) or not compiler_id.strip() or not callable(invoke)):
            raise SupportError('explicit experiment, compiler and transport identities are required')
        root.mkdir(parents=True, exist_ok=True, mode=0o700)
        with _writer_lock(root):
            if any(p.name != '.publication.lock' for p in root.iterdir()):
                raise SupportError('new experiments must start in an empty directory')
            store = MemoryStore(root, legacy_dirs=[])
            store.initialize(namespace=namespace)
            snapshot = load_snapshot(root, namespace=namespace)
            publication = prepare_publication(snapshot, invoke, compiler_id=compiler_id)
            publish(root/'published', publication, expected_namespace=namespace)
        return cls(root, namespace=namespace, compiler_id=compiler_id, invoke=invoke)

    def enqueue_user(self, *, task_id: str, session_id: str, event_id: str, source_text: str,
                     public_task: str = '', context_reference=None):
        if any(not isinstance(v, str) or not v.strip() for v in (task_id, session_id, event_id, source_text)):
            raise SupportError('task, event and complete user text are required')
        if context_reference is not None and (not isinstance(context_reference, dict)
                or context_reference.get('session_id') != session_id):
            raise SupportError('context reference does not belong to the current task session')
        if not isinstance(public_task, str):
            raise SupportError('public task context must be text')
        turn_key = 'experiment-' + digest({'task': task_id, 'event': event_id})
        context={'namespace':self.namespace,'phase':'training','scope':'user_event',
                 'task_id':task_id,'session_id':session_id,'event_id':event_id}
        # Validate identities locally, without binding a model owner or calling
        # any model in the foreground admission path.
        bind_context(lambda prompt:None,context)
        origin={**context,'schema':1,'turn_key':turn_key,'source_digest':digest(source_text),
                'public_task_digest':digest(public_task)}
        # This short lock serializes admission against closing training; it is
        # never held over model calls or a SQLite transaction.
        with _writer_lock(self.root):
            if (self.root/'closed-to-input.json').exists() or (self.root/'frozen.json').exists():
                raise SupportError('training admission is closed; test feedback cannot update memory')
            origin_path=self._origin_path(turn_key)
            if origin_path.parent.is_symlink():
                raise SupportError('learning origin directory cannot be a symlink')
            origin_path.parent.mkdir(exist_ok=True,mode=0o700)
            if origin_path.exists():
                if json.loads(_read(origin_path))!=origin:
                    raise SupportError('one user event has conflicting learning origins')
            else:
                _atomic_write(origin_path,canonical(origin),0o600)
            return memory_upsert.enqueue(source_text, turn_key=turn_key,
                context='Public current task (context, not additional authorization):\n'+public_task,
                context_reference=context_reference, memory_dir=self.root,
                namespace=self.namespace, spawn_worker=False, force=True, detect_signal=True)

    def _origin_path(self,turn_key):
        directory=self.root/'.event-origins'
        if directory.is_symlink():
            raise SupportError('learning origin directory cannot be a symlink')
        return directory/(digest(turn_key)+'.json')

    def process_pending(self, *, limit: int = 20):
        if type(limit) is not int or limit < 1:
            raise SupportError('positive worker batch limit is required')
        # One background worker owns processing/publication. A separate short
        # admission lock above lets new prompts enqueue while model work runs.
        with _writer_lock(self.publications):
            if (self.root/'frozen.json').exists():
                raise SupportError('frozen memory cannot run a learning worker')
            requests=_TrainingRequests(self)
            store=MemoryStore(self.root,legacy_dirs=[])
            recovered=[]
            def recover(turn_key):
                receipt=store.learning_recovery(turn_key)
                status=store.get_turn(turn_key)['status']
                if receipt and receipt['epoch']==1 and status in {'pending','resolving'}:
                    if receipt['generation']!=store.generation():
                        raise SupportError('a newer memory commit precedes unfinished learning recovery')
                    recovered.append(memory_upsert.resolve_turn(turn_key,memory_dir=self.root,invoke=requests))
                    return
                if (not receipt or receipt['epoch']!=0 or receipt['generation']!=store.generation() or status!='failed' or
                        not callable(getattr(type(self.invoke),'request_validated',None))):
                    return
                delay=receipt['not_before']-time.time()
                if delay>0:
                    time.sleep(min(delay,60))
                if store.resume_failed_learning(turn_key,namespace=self.namespace):
                    recovered.append(memory_upsert.resolve_turn(turn_key,memory_dir=self.root,invoke=requests))
            # A crash after marking failure cannot lose its recovery receipt.
            for receipt in store.learning_recovery():
                recover(receipt['turn_key'])
            batches=[]
            for _ in range(limit):
                if any(row['epoch']==1 for row in store.learning_recovery()):
                    raise SupportError('unfinished recovery must complete before processing newer training inputs')
                result=memory_upsert.drain(self.root,limit=1,invoke=requests)
                batches.extend(result['results'])
                for item in result['results']:
                    if item.get('status')=='failed' and item.get('turn_key'):
                        recover(item['turn_key'])
                if not result['remaining']:
                    break
            result={**result,'results':batches,'count':len(batches),'learning_recoveries':recovered,
                'remaining':bool(memory_upsert._pending_request_paths(self.root) or
                                 store.pending_turn_keys(limit=1) or store.projection_pending())}
            if any((self.root/memory_upsert.INBOX_DIRNAME/'failed').glob('*.failed')):
                raise SupportError('quarantined learning requests require review before continuing this experiment')
            snapshot = load_snapshot(self.root, namespace=self.namespace)
            previous = load_publication(self.publications, expected_namespace=self.namespace)
            compiler=bind_context(self.invoke,{'namespace':self.namespace,'phase':'training','scope':'publication',
                'task_id':'__library__','session_id':'__publication__','event_id':snapshot.digest})
            publication = prepare_publication(snapshot, compiler, compiler_id=self.compiler_id, previous=previous)
        # publish has its own writer lock and refuses version rollback. Only
        # one experiment worker should call this API; the runtime reads JSON.
        publish(self.publications, publication, expected_namespace=self.namespace)
        return {**result, 'publication_digest': publication.digest, 'generation': publication.generation,
                'pending_rule_ids': list(publication.pending_ids)}

    def finish_training(self, *, max_passes: int = 10, batch_limit: int = 20):
        if type(max_passes) is not int or max_passes < 1:
            raise SupportError('positive drain pass limit is required')
        with _writer_lock(self.root):
            if (self.root/'frozen.json').exists():
                return self.frozen_publication()
            _atomic_write(self.root/'closed-to-input.json', canonical({'namespace': self.namespace}), 0o600)
        for _ in range(max_passes):
            outcome = self.process_pending(limit=batch_limit)
            if not outcome['remaining']:
                break
        else:
            raise SupportError('training worker still has pending work; no test snapshot was exported')
        # Serializes with processing while validating that all committed rules
        # and their prepared support are represented in the exported version.
        with _writer_lock(self.publications):
            if any((self.root/memory_upsert.INBOX_DIRNAME).glob('.*.json.tmp.*')):
                raise SupportError('unpublished inbox requests remain; no test snapshot was exported')
            snapshot = load_snapshot(self.root, namespace=self.namespace)
            publication = load_publication(self.publications, expected_namespace=self.namespace)
            if publication.snapshot.digest != snapshot.digest:
                raise SupportError('learning changed after publication; finish the worker before freezing')
            # A reminder/pending support that the last training update left repairable gets its recompilation
            # here instead of on a later generation that a frozen library never has (2026-10-06, item 51:
            # ClawArena round 30 froze the opening-lines card as a reminder after its fifth revision failed once).
            compiler = bind_context(self.invoke, {'namespace': self.namespace, 'phase': 'training', 'scope': 'publication',
                                                  'task_id': '__library__', 'session_id': '__publication__',
                                                  'event_id': snapshot.digest + ':freeze'})
            repairable = any(s.tier in {'reminder', 'pending'} and json.loads(s.validation_json).get('repairable')
                             for s in getattr(publication, 'supports', ()))
            repaired = repair_publication(publication, compiler, compiler_id=self.compiler_id) if repairable else publication
            freeze_recompiled = [rule.atomic_id for rule, before, after in
                                 zip(publication.snapshot.rules, getattr(publication, 'supports', ()), getattr(repaired, 'supports', ()))
                                 if before != after]
            if freeze_recompiled:
                publish(self.publications, repaired, expected_namespace=self.namespace)
                publication = repaired
            store = MemoryStore(self.root, legacy_dirs=[])
            # A clarification the lifecycle asked and nobody answered before the input closed is dismissed here and
            # listed in the audit: the clear part of such a turn was already committed (mixed plans), the ambiguous
            # clause is not learned, and a frozen library has no later user turn that could answer (2026-10-07,
            # item 53: formal sol x xq x ClawArena could never freeze on one parked needs_user turn, 48 retries).
            dismissed_at_freeze = [row['turn_key'] for row in store.needs_user_turns(limit=1000)]
            for turn_key in dismissed_at_freeze:
                store.dismiss_clarification(turn_key)
            with store.connection() as conn:
                counts = {row['status']: row['n'] for row in conn.execute('SELECT status, COUNT(*) AS n FROM turns GROUP BY status')}
            _atomic_write(self.root/'freeze-audit.json', canonical({'namespace': self.namespace,
                'publication_digest': publication.digest, 'turn_outcomes': counts,
                'pending_rule_ids': list(publication.pending_ids), 'freeze_recompiled': freeze_recompiled,
                'dismissed_at_freeze': dismissed_at_freeze}), 0o400)
            self._require_completed_learning(counts, publication)
            _atomic_write(self.root/'frozen.json', publication.to_json(), 0o400)
        return publication

    @staticmethod
    def _require_completed_learning(counts, publication):
        completed = {'projected', 'noop', 'clarified', 'dismissed', 'rejected'}
        incomplete = {key: count for key, count in counts.items() if count and key not in completed}
        if incomplete:
            # Failed requests remain evidence. Draining a scheduler does not
            # turn a failed learner into completed training or grant retries.
            raise SupportError('learning or projection incomplete at freeze: '+canonical(incomplete))
        if publication.pending_ids:
            raise SupportError('rule support is unpublished; no complete test snapshot was exported')

    def frozen_publication(self) -> Publication:
        publication = Publication.from_json(_read(self.root/'frozen.json'), expected_namespace=self.namespace)
        # Reopening a historical receipt must apply the same admission check,
        # without migrating, retrying, or rewriting its preserved database.
        path = self.root/DB_FILENAME
        if path.is_symlink():
            raise SupportError('frozen learning evidence cannot be a symlink')
        conn = sqlite3.connect(path.as_uri()+'?mode=ro', uri=True)
        try:
            counts = dict(conn.execute('SELECT status, COUNT(*) FROM turns GROUP BY status'))
        finally:
            conn.close()
        self._require_completed_learning(counts, publication)
        return publication
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall