Summary

Phase 1 of the KR-KORA-PIP-RESTRUCTURE program. Two new pip-installable packages under packages/, extracted from in-tree code with full backward-compat shims so existing imports work unchanged.

• packages/isokron-client/ — 20 substrate-functional modules lifted from plugins/memory/isokron/ (non-provider files only). Pure library with zero Kora/Hermes coupling at import time. ANY Hermes-based agent can pip install isokron-client to gain IsoKron substrate primitives. Public surface: events / reads / control / scratchpad / policy / constitution / capability / sea_tickets. 5/5 dry-run smoke tests pass in a clean venv. See packages/isokron-client/README.md §"BYOA usage example".
• packages/kora-runtime/ — 28 modules (7 sub-plugins + orchestrator) lifted from kora_cli/reasoning/kora_hermes_plugin/. Declares isokron-client as a PyPI dep. Hermes is source-only per the 2026-05-25 operator decision; README documents the install order. Entry point hermes_agent.plugins.kora = kora_runtime:register validated via importlib.metadata.entry_points() after dry-run install. 5/5 dry-run smoke tests pass + 142/151 in-tree tests pass (8 pre-existing Marvin data-dir failures unrelated; 0 regressions).

§4 STOP-ASK resolution

The bucket's K-DG block hypothesized the IsoKron client at kora_cli/isokron/. PM-verify pass found it at plugins/memory/isokron/ (29 files, IS a Hermes MemoryProvider plugin). API shape in reality: events / reads / control / scratchpad / ... — not the bucket's strawman audit / conversation / workspace. Surfaced to operator; operator confirmed (B) tight-scoped:

• Pure library half (20 modules) → isokron-client
• provider.py + active_provider.py + active_poller.py + sea_ticket_poller* + tools/ → STAY in plugins/memory/isokron/ importing FROM isokron-client
• kora_cli/clients/kora_control_writer.py + kora_cli/audit/jsonl_sink.py → deferred to Phase 1b (operator task fix: correct KawaiiSpinner file location in AGENTS.md NousResearch/hermes-agent#450)
• Surface uses real grep'd names, drops the strawman

Back-compat mechanics

Both shims (plugins/memory/isokron/__init__.py + kora_cli/reasoning/kora_hermes_plugin/__init__.py) do sys.path bootstrap (mirrors plugins/marvin/__init__.py POC from #204) plus sys.modules aliasing of the moved sub-modules. Existing in-tree imports continue working unchanged — no per-file shim files, no caller sweep across the rest of the Kora tree. Test logger names in 6 test files updated from plugins.memory.isokron.X → isokron_client.X for moved modules; STAY-module loggers untouched.

Build/install transcripts

$ python -m build --wheel    # packages/isokron-client/
Successfully built isokron_client-0.1.0a1-py3-none-any.whl

$ uv pip install --python /tmp/isokron-dry/bin/python \\
    ./packages/isokron-client/dist/isokron_client-0.1.0a1-py3-none-any.whl
Installed 1 package: isokron-client==0.1.0a1
$ python -c "import isokron_client; print(f'v{isokron_client.__version__}, modules={len(isokron_client.__all__)}')"
v0.1.0a1, modules=20
$ pytest packages/isokron-client/tests/
5 passed in 0.06s

$ python -m build --wheel    # packages/kora-runtime/
Successfully built kora_runtime-0.1.0a1-py3-none-any.whl

$ uv pip install --python /tmp/kora-runtime-dry/bin/python \\
    ./packages/isokron-client/dist/isokron_client-0.1.0a1-py3-none-any.whl
$ uv pip install --python /tmp/kora-runtime-dry/bin/python \\
    ./packages/kora-runtime/dist/kora_runtime-0.1.0a1-py3-none-any.whl
$ python -c "import importlib.metadata as md; \\
    print([(e.name, e.value) for e in md.entry_points(group='hermes_agent.plugins')])"
[('kora', 'kora_runtime:register')]
$ pytest packages/kora-runtime/tests/
5 passed in 0.02s

AUDIT.md closure

Companion PR on rafe-walker/kora-docs amends kora_docs/14_research/kora_pip_packaging_2026-05-24/AUDIT.md from 4-package to 5-package split + closes §7.1 (Hermes source-only) + §7.2 (isokron-client separate package, BYOA). See docs/kora-KR-KORA-PIP-RESTRUCTURE-PHASE-1-RUNTIME-AND-ISOKRON-CLIENT-MEGABUCKET on kora-docs.

Test plan

• packages/isokron-client/tests/ smoke tests (5/5) against fresh-venv wheel install
• packages/kora-runtime/tests/ smoke tests (5/5) against fresh-venv wheel install + entry-point discovery
• Existing tests/plugins/memory/ suite — 369/374 pass (5 failures all pre-existing on baseline; 0 regressions)
• Existing tests/plugins/test_kora_hermes_plugin_*.py + tests/kora_cli/reasoning/kora_hermes_plugin/ — 142/151 pass (8 pre-existing Marvin failures; 0 regressions)
• tests/kora_cli/router/test_cost_router.py + tests/kora_cli/short_circuit/test_dm_phrasebook.py canonical-path assertions updated to kora_runtime.* (the canonical module path post-move)
• Operator review of BYOA README + adapted API surface naming
• Operator decision on next dispatch: KR-KORA-PIP-RESTRUCTURE-PHASE-2-CLI vs Phase 1b cleanup (kora_control_writer + JSONL sink into isokron-client)

🤖 Generated with Claude Code