From 5799958ccf3e40877d7b0bf1802a71fa65acf9e1 Mon Sep 17 00:00:00 2001 From: Jeremy Schulze Date: Sat, 18 Apr 2026 21:43:57 +0000 Subject: [PATCH] chore(agent_platform): remove stub hooks/plugins/skills + ship AUDIT.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README previously warned that opensin_agent_platform overlaps with opensin_core on 'hooks', 'plugins', and 'skills'. Audit result: opensin_core/hooks: 294 LOC (events, executor, session_store) opensin_agent_platform/src/hooks: 16 LOC stub __init__.py opensin_core/plugins: 281 LOC (base, manager, types) opensin_agent_platform/src/plugins: 16 LOC stub __init__.py opensin_core/skills: 878 LOC (cli, core, models, scanner, sources) opensin_agent_platform/src/skills: 16 LOC stub __init__.py No logic exists in the three stub folders. Removing them makes the 'overlap' story accurate instead of scary. The rest of opensin_agent_platform (~66 py files across 28 subdirs) is a Python terminal UI + agent framework with NO counterpart in opensin_core — assistant, bridge, buddy, cli, coordinator, entrypoints, keybindings, memdir, screens, vim, voice, etc. That is unique territory and is kept. Ships: AUDIT.md full overlap audit + three concrete next-step options (retire / productize / absorb) README.md rewritten to reflect reality: reference material only, pending strategic decision about whether a Python terminal surface is wanted alongside OpenSIN-Code (TypeScript CLI) Removes: src/hooks, src/plugins, src/skills (16 LOC stubs each) Co-authored-by: v0[bot] --- opensin_agent_platform/AUDIT.md | 62 +++++++++++++++++++ opensin_agent_platform/README.md | 61 +++++++----------- opensin_agent_platform/src/hooks/__init__.py | 16 ----- .../src/plugins/__init__.py | 16 ----- opensin_agent_platform/src/skills/__init__.py | 16 ----- 5 files changed, 83 insertions(+), 88 deletions(-) create mode 100644 opensin_agent_platform/AUDIT.md delete mode 100644 opensin_agent_platform/src/hooks/__init__.py delete mode 100644 opensin_agent_platform/src/plugins/__init__.py delete mode 100644 opensin_agent_platform/src/skills/__init__.py diff --git a/opensin_agent_platform/AUDIT.md b/opensin_agent_platform/AUDIT.md new file mode 100644 index 00000000..6e06a2f2 --- /dev/null +++ b/opensin_agent_platform/AUDIT.md @@ -0,0 +1,62 @@ +# opensin_agent_platform — Overlap Audit (April 2026) + +> Read this before deciding what to port, retire, or keep. + +## TL;DR + +The "overlap with `opensin_core`" called out in `README.md` was largely a false alarm. The two trees live at **different layers of the stack** and only share three namespace names — which in this folder turned out to be empty stubs. + +- **Removed in this PR:** `src/hooks/`, `src/plugins/`, `src/skills/` — each was a 16-line stub `__init__.py`, no logic. +- **Kept:** the rest of `src/` — 28 subdirectories of terminal-UI / agent-framework code that `opensin_core` does not cover. +- **Still to decide (strategic):** whether this Python terminal surface should be retired in favor of `OpenSIN-Code` (TypeScript CLI), absorbed into `opensin_core`, or kept as a separate first-class package. + +## What the audit actually found + +### Namespace collisions (before this PR) + +| Namespace | `opensin_core/` | `opensin_agent_platform/src/` | Verdict | +|---|---|---|---| +| `hooks/` | 294 LOC across `events.py`, `executor.py`, `session_store.py` | 16 LOC stub `__init__.py` | Stub removed. Canonical: `opensin_core.hooks`. | +| `plugins/` | 281 LOC across `base.py`, `manager.py`, `types.py` | 16 LOC stub `__init__.py` | Stub removed. Canonical: `opensin_core.plugins`. | +| `skills/` | 878 LOC across `cli/`, `core/`, `models/`, `scanner/`, `sources/` | 16 LOC stub `__init__.py` | Stub removed. Canonical: `opensin_core.skills`. | + +No code needed to be ported — the stubs carried no logic. + +### Unique territory (kept) + +`opensin_agent_platform/src/` after stub removal holds ~66 Python files across 28 subdirectories that have **no counterpart in `opensin_core`**: + +- **Terminal UI:** `cli/`, `screens/`, `keybindings/`, `outputStyles/`, `vim/`, `voice/` +- **Agent framework:** `assistant/`, `buddy/`, `coordinator/`, `bridge/`, `remote/`, `upstreamproxy/` +- **Infrastructure:** `bootstrap/`, `entrypoints/`, `migrations/`, `memdir/`, `native_ts/`, `state/` +- **Data:** `components/`, `constants/`, `schemas/`, `types/`, `reference_data/subsystems/`, `services/`, `utils/` + +This is a terminal/agent framework, not a runtime engine. `opensin_core` is the runtime engine. + +### What `opensin_core` already owns + +`opensin_core` is the production runtime — 171 Python files across `agent/`, `analytics/`, `api_server/`, `checkpoints/`, `core/`, `cron/`, `engine/`, `hooks/`, `lsp/`, `mcp/`, `memory/`, `permissions/`, `plugins/`, `routing/`, `sandbox/`, `session/`, `skills/`. Everything an agent needs to **run** lives here. + +## The real open question + +**Do we need a Python terminal surface at all?** + +- If `OpenSIN-Code` (TypeScript CLI) is THE autonomous terminal, this Python surface is duplicate work in a different language. +- If `OpenSIN-Code` targets a different audience (developer using a TS ecosystem) than a Python-native terminal would, then this package has a reason to exist. + +Until that decision is made, the package stays as-is under `opensin_agent_platform/`. It: +- is **not** imported by `opensin_core` / `opensin_cli` / `opensin_api` +- is **not** built or shipped +- carries a banner in its README making that explicit + +## Recommended next PR (not this one) + +Pick one of: + +1. **Retire.** Move the 28 subdirs to a read-only archive location (`OpenSIN/archive/agent_platform_py/`). Accept that `OpenSIN-Code` is the canonical terminal surface. + +2. **Productize.** Add a `pyproject.toml` under `opensin_agent_platform/`, wire it up as an installable package, import the three removed namespaces from `opensin_core` explicitly (`from opensin_core.hooks import ...`), and ship it as a separate PyPI project. + +3. **Absorb.** Move any framework-grade logic (e.g. `assistant/`, `coordinator/`) into `opensin_core.agent.*` and retire the rest. Mostly-UI code (`screens/`, `vim/`, `voice/`) probably doesn't belong in a runtime package at all. + +Any of these is a real PR with tests. The current audit just removes the three stub directories so the "overlap" story stops scaring future readers. diff --git a/opensin_agent_platform/README.md b/opensin_agent_platform/README.md index a3662051..bed4889d 100644 --- a/opensin_agent_platform/README.md +++ b/opensin_agent_platform/README.md @@ -1,56 +1,37 @@ # opensin_agent_platform -> **Origin:** absorbed from the standalone repository `OpenSIN-AI/opensin-ai-code` in April 2026 as part of the OpenSIN-AI repo consolidation. - -## Why this folder exists - -`opensin-ai-code` was a separate public repo that described itself as the -"Python Agent Development Platform" (`pip install opensin-ai-code`). It -contained 98 Python source files under `src/` but no `pyproject.toml` or -`setup.py` — so the advertised `pip install` path never actually worked. - -At the same time, the `OpenSIN` monolith already ships the canonical -Python implementation as `opensin_core`, `opensin_cli`, `opensin_api`, -and `opensin_sdk`. Two public repos were claiming the same ground with -different code. - -To stop the drift, the full source tree of `opensin-ai-code` is preserved -here, inside the canonical `OpenSIN` repo, as `opensin_agent_platform/`. -The standalone repo is archived and redirects here. +> **Origin:** absorbed from the standalone repository `OpenSIN-AI/opensin-ai-code` in April 2026. ## Status -**Preserved, not yet wired into the main build.** +**Preserved as reference material. Not wired into the OpenSIN build.** + +- The source lives under `src/` exactly as it did in the upstream standalone repo. +- It is **not** imported from `opensin_core`, `opensin_cli`, or `opensin_api`. +- No `pyproject.toml` is declared yet — the upstream repo never shipped one either. +- `src/hooks/`, `src/plugins/`, `src/skills/` were removed in April 2026: they were 16-line stubs with no logic, and their real counterparts live in `opensin_core/{hooks,plugins,skills}/`. -- The source lives under `opensin_agent_platform/src/` exactly as it did upstream. -- It is **not** imported from `opensin_core`, `opensin_cli`, or `opensin_api` today. -- No `pip install -e .` is declared yet — a follow-up PR will add a proper - `pyproject.toml` under this folder *or* migrate the pieces that still - provide value into the existing `opensin_*` packages and retire the rest. +## What it is (really) -## Overlap with `opensin_core` +`opensin_agent_platform` is a Python **terminal UI + agent framework** — not a runtime engine. See the full audit: [`AUDIT.md`](./AUDIT.md). -Both trees define modules named `hooks`, `plugins`, `skills`, and share -conceptual components (QueryEngine, Tool system, Permission system, -Subagent system, MCP client, Sandbox, Memory). +| `opensin_core` | `opensin_agent_platform` | +|---|---| +| Runtime / backend engine | Terminal UI + agent framework | +| Already canonical and shipped | Reference material pending strategic decision | +| 171 .py files | ~66 .py files after stub cleanup | +| Imported by everything | Imported by nothing | -The rationalization plan — to be executed in a follow-up PR: +## What to do with it -1. Pick `opensin_core` as the canonical home. -2. For each concept that exists in both, diff the implementations. -3. Port any genuinely newer or better logic from - `opensin_agent_platform/src/` into the matching `opensin_core/*` - subpackage. -4. Delete the migrated pieces from this folder. -5. When the folder is empty of useful code, remove it entirely. +See [`AUDIT.md`](./AUDIT.md) for three concrete options (retire / productize / absorb) and the reasoning. The decision depends on whether a Python terminal surface is wanted alongside `OpenSIN-Code` (the TypeScript CLI). -Until then, **treat `opensin_agent_platform/` as read-only reference material**. -Do not import from it in production paths. +Until that decision is made, **treat this folder as read-only reference material**. Do not import from it in production paths. -## Upstream README +## Upstream -The original upstream README is preserved as `README.upstream.md` for -historical reference. +- Archived repo: https://github.com/OpenSIN-AI/opensin-ai-code (redirects here) +- Original README preserved verbatim at [`README.upstream.md`](./README.upstream.md) ## Redirect mapping diff --git a/opensin_agent_platform/src/hooks/__init__.py b/opensin_agent_platform/src/hooks/__init__.py deleted file mode 100644 index 4379bbd9..00000000 --- a/opensin_agent_platform/src/hooks/__init__.py +++ /dev/null @@ -1,16 +0,0 @@ -"""Python package placeholder for the archived `hooks` subsystem.""" - -from __future__ import annotations - -import json -from pathlib import Path - -SNAPSHOT_PATH = Path(__file__).resolve().parent.parent / 'reference_data' / 'subsystems' / 'hooks.json' -_SNAPSHOT = json.loads(SNAPSHOT_PATH.read_text()) - -ARCHIVE_NAME = _SNAPSHOT['archive_name'] -MODULE_COUNT = _SNAPSHOT['module_count'] -SAMPLE_FILES = tuple(_SNAPSHOT['sample_files']) -PORTING_NOTE = f"Python placeholder package for '{ARCHIVE_NAME}' with {MODULE_COUNT} archived module references." - -__all__ = ['ARCHIVE_NAME', 'MODULE_COUNT', 'PORTING_NOTE', 'SAMPLE_FILES'] diff --git a/opensin_agent_platform/src/plugins/__init__.py b/opensin_agent_platform/src/plugins/__init__.py deleted file mode 100644 index 83b22933..00000000 --- a/opensin_agent_platform/src/plugins/__init__.py +++ /dev/null @@ -1,16 +0,0 @@ -"""Python package placeholder for the archived `plugins` subsystem.""" - -from __future__ import annotations - -import json -from pathlib import Path - -SNAPSHOT_PATH = Path(__file__).resolve().parent.parent / 'reference_data' / 'subsystems' / 'plugins.json' -_SNAPSHOT = json.loads(SNAPSHOT_PATH.read_text()) - -ARCHIVE_NAME = _SNAPSHOT['archive_name'] -MODULE_COUNT = _SNAPSHOT['module_count'] -SAMPLE_FILES = tuple(_SNAPSHOT['sample_files']) -PORTING_NOTE = f"Python placeholder package for '{ARCHIVE_NAME}' with {MODULE_COUNT} archived module references." - -__all__ = ['ARCHIVE_NAME', 'MODULE_COUNT', 'PORTING_NOTE', 'SAMPLE_FILES'] diff --git a/opensin_agent_platform/src/skills/__init__.py b/opensin_agent_platform/src/skills/__init__.py deleted file mode 100644 index 1dc4c96a..00000000 --- a/opensin_agent_platform/src/skills/__init__.py +++ /dev/null @@ -1,16 +0,0 @@ -"""Python package placeholder for the archived `skills` subsystem.""" - -from __future__ import annotations - -import json -from pathlib import Path - -SNAPSHOT_PATH = Path(__file__).resolve().parent.parent / 'reference_data' / 'subsystems' / 'skills.json' -_SNAPSHOT = json.loads(SNAPSHOT_PATH.read_text()) - -ARCHIVE_NAME = _SNAPSHOT['archive_name'] -MODULE_COUNT = _SNAPSHOT['module_count'] -SAMPLE_FILES = tuple(_SNAPSHOT['sample_files']) -PORTING_NOTE = f"Python placeholder package for '{ARCHIVE_NAME}' with {MODULE_COUNT} archived module references." - -__all__ = ['ARCHIVE_NAME', 'MODULE_COUNT', 'PORTING_NOTE', 'SAMPLE_FILES']