Summary

Comprehensive architecture modernization of kash based on a code review and planning spec. Includes dependency upgrades from PR #5, Python 3.14 CI support, and all Tier 1 beads plus partial Tier 2/3 work.

Scope: 244 files changed, 5,266 additions, 140 deletions. 301 tests (up from ~135 on main).

Key changes

• Standalone library API (kash.run): kash_init() + kash_run() for using kash programmatically without the interactive shell
• Clean public API surface (kash/__init__.py): __all__ with 28 canonical exports; all deep import paths preserved
• Lazy action/command registration: ensure_actions_registered() / ensure_commands_registered() replace module-level side effects
• Dependency upgrades: openai 1.99.9 → 2.17.0, litellm → 1.81.9, all transitive deps upgraded
• Dependency cleanup: Removed 6 unused deps; added optional groups [llm], [web], [media], [server], [shell], [all]
• Python modernization: from __future__ import annotations (184 files), @override (34 methods), named constants, dead code removal
• CI: Added Python 3.14 to matrix (3.11–3.14 all green), uv 0.9.5 → 0.9.26
• Test infrastructure: 21 new test files, conftest.py with shared fixtures, 301 total tests

Validation Plan

Part 1: Automated — Verified by CI (all passing)

CI runs on Python 3.11, 3.12, 3.13, 3.14 — all 4 builds green.

Test coverage breakdown:

Part 2: Manual Verification Required — Human Review Checklist

These items cannot be fully validated by automated tests and require a human to confirm.

2a. Backward Compatibility (HIGH PRIORITY)

• Deep imports still work: Verify existing code using deep import paths is unbroken:

  from kash.model.items_model import Item          # should still work
  from kash.exec.action_decorators import kash_action  # should still work
  from kash import Item                             # new convenience import

• Downstream packages: If kash-docs or kash-media exist as separate packages, verify they still import from kash without errors
• Shell startup: Run kash interactively and verify:
  • Shell prompt appears
  • Tab completion works
  • help command works
  • Actions are discoverable (lazy registration triggers on first use)
• Kit loading: If any kits are installed, verify they still load and their actions are available

2b. OpenAI 2.x + LiteLLM Compatibility (HIGH PRIORITY)

• LLM action smoke test: Run an actual LLM-backed action (e.g. summarize_as_bullets) with a real API key and verify:
  • API call succeeds (no import/type errors from openai 2.x)
  • Response format is correct
  • Streaming works (if used)
• Embedding model: If embeddings are used, verify text-embedding-3-large still works with openai 2.x

2c. Standalone Library API (MEDIUM PRIORITY)

• Real action execution: Test kash_run() outside the shell with a real (non-mocked) action:

  from kash import kash_init, kash_run
  kash_init()
  result = kash_run("strip_html", ["https://example.com"])
  print(result)  # should have items with body content

• Workspace behavior: Verify results save correctly to the specified workspace directory
• Error handling: Verify meaningful errors for invalid action names or bad inputs

2d. Optional Dependency Groups (MEDIUM PRIORITY)

• Minimal install: pip install kash-shell (or uv pip install .) — verify core imports work without optional extras
• Group installs: Test each group individually:
  • pip install kash-shell[llm] — LLM actions available
  • pip install kash-shell[web] — Web scraping works
  • pip install kash-shell[all] — Everything works

2e. Lazy Registration Behavior (LOW PRIORITY)

• Startup time: Compare time kash --version before and after this PR — should be equal or faster
• First action call: Verify no perceptible delay on first action execution (registration happens transparently)
• Idempotency: Calling ensure_actions_registered() multiple times doesn't re-import or duplicate

2f. Documentation Accuracy (LOW PRIORITY)

• Architecture spec: Skim the planning spec — verify implementation matches what's described
• Spec checkboxes: Verify the [x] marks in the spec match actual bead status

Part 3: Known Issues & Risk Areas

Follow-Up Work (Post-Merge)

The remaining 5 open beads are all Tier 2/3 features that build on this PR's foundation. They should be tackled in a follow-up PR after this one merges.

Tier 2: Remaining Additive Features (4 beads)

These add new capabilities without breaking existing imports. They build on the lazy registration and kash.run() foundation from this PR.

1. ShellContext Protocol (kash-0vb5) — P2, blocks kash-5ew2

Goal: Decouple command execution from xonsh via a ShellContext protocol.

Design:

class ShellContext(Protocol):
    def set_env(self, name: str, value: Any) -> None: ...
    def print_output(self, content: str) -> None: ...
    def get_workspace(self) -> Workspace: ...
    def record_history(self, command: str) -> None: ...

Implementations needed:

• XonshShellContext — wraps current xonsh environment (preserves existing behavior)
• StandaloneContext — for library/script use (builds on kash.run)
• CLIContext — for standalone CLI commands

Why deferred: Design needs careful thought to avoid leaking xonsh internals. The protocol must be stable since downstream code will depend on it.

2. Standalone CLI for Actions (kash-qejq) — P2

Goal: Enable kash run <action> --input ... --format json without starting the interactive shell.

Design:

• Typer or argparse-based CLI entry point
• Uses kash_run() from this PR as the execution backend
• Supports --format text|json, --non-interactive, --no-progress, --dry-run
• Exit codes: 0=success, 1=error, 2=validation, 130=SIGINT

Why deferred: Depends on ShellContext (kash-0vb5) for clean output routing. Could be started independently with a simpler approach.

3. --format json and --non-interactive Flags (kash-5ew2) — P2, blocked by kash-0vb5

Goal: Machine-readable output for agent/CI consumption.

Design:

• OutputManager pattern for dual text/JSON output
• Route data to stdout, errors/warnings to stderr
• Disable spinners/progress in non-TTY contexts
• Respect CI and NO_COLOR env vars

Why deferred: Blocked by ShellContext protocol (kash-0vb5) — needs the abstraction to route output correctly.

4. KashTestRunner (kash-j8st) — P2

Goal: First-class testing support for running kash actions in pytest.

Design:

from kash.testing import KashTestRunner

runner = KashTestRunner(workspace=tmp_path)
result = runner.run_action("strip_html", item_with_html)
assert "clean text" in result.body

# Pipeline testing
result = runner.run_pipeline([
    ("fetch_url", {"url": "https://example.com"}),
    ("strip_html", {}),
    ("summarize_as_bullets", {"model": "gpt-5"}),
])

Requirements: No console output during test runs, deterministic behavior (mock LLM), easy workspace setup/teardown, assert-friendly return types.

Why deferred: Builds on kash.run() from this PR but needs more design work around mock injection and pipeline composition.

Tier 3: Breaking Changes (1 bead)

5. Lightweight MCP Mode (kash-s9q0) — P3

Goal: Expose individual actions as MCP tools without loading the entire kash registry.

Current problem: The MCP server requires full kash initialization including all registries, workspace system, and configuration. Cannot expose a single action as an MCP tool without loading everything.

Design considerations:

• Selective action loading (only import what's needed)
• Direct Claude Code skill integration (without running MCP server)
• Skill template generation from @kash_action metadata

Why deferred: This is the only Tier 3 (potentially breaking) item remaining. It may change how action discovery works internally. Benefits from the lazy registration work in this PR (kash-y80s) as a foundation.

Prerequisite evaluations (completed in this PR):

• kash-zt0y: Utils audit → no reorganization needed
• kash-law6: web_content extraction → NOT ready (5/10 independence)
• kash-78wq: llm_utils extraction → partially feasible but premature

Recommended Order

kash-0vb5 (ShellContext)
    ↓
kash-qejq (Standalone CLI)  +  kash-j8st (KashTestRunner)
    ↓
kash-5ew2 (--format json flags)
    ↓
kash-s9q0 (Lightweight MCP) — can be done independently

Beads

Closed (19): kash-keim, kash-ermq, kash-ppz9, kash-jlmn, kash-aik9, kash-gpj8, kash-69rw, kash-kngd, kash-hv4e, kash-ht5b, kash-gzzs, kash-91re, kash-ymq4, kash-y80s, kash-i7dr, kash-8hh2, kash-zt0y, kash-law6, kash-78wq

Open (5): kash-0vb5, kash-qejq, kash-5ew2, kash-j8st, kash-s9q0

Subsumes: PR #5 (dependency upgrades, CODE_REVIEW doc, CI uv update). PR #5 can be closed.

https://claude.ai/code/session_01Pv152sQEpeLvwDoJTdz9Fm