feat: add an installable Codex plugin preview

docs/codex-plugin.md

@@ -0,0 +1,171 @@
+# InferRSI plugin for Codex (local preview)
+
+Use InferRSI from a Codex conversation in your target repository: research a
+bottleneck, prepare a comparison, or inspect an existing run. This is the Codex
+implementation slice of [RFC #152](https://github.com/InferMatrixLab/InferRSI/issues/152);
+DSH/openJiuwen integration and a measured usability comparison remain separate.
+
+## Install from the GitHub preview
+
+Give Codex the [preview installation page](https://github.com/zengchuang-hw/OmniRSI/tree/codex/inferrsi-plugin-preview)
+and ask it to install InferRSI. On Windows, use the following PowerShell route
+to fetch only the generated branch and enable long paths for this Git operation:
+
+```powershell
+$pluginInstallDir = Join-Path $env:LOCALAPPDATA "InferRSI/codex-plugin-preview"
+git -c core.longpaths=true clone --depth 1 --single-branch --branch codex/inferrsi-plugin-preview https://github.com/zengchuang-hw/OmniRSI $pluginInstallDir
+codex plugin marketplace add $pluginInstallDir
+codex plugin add inferrsi@inferrsi-preview
+codex plugin list --marketplace inferrsi-preview --json
+```
+
+Choose a fresh directory, or inspect an existing installation before reusing it.
+This does not change global Git configuration. Direct Git marketplace registration
+on the tested Windows client first checked out the repository's default branch
+and hit the platform's path-length limit; the explicit single-branch clone avoids
+that unrelated checkout. Other clients may use the native Git-source route:
+
+```text
+codex plugin marketplace add https://github.com/zengchuang-hw/OmniRSI --ref codex/inferrsi-plugin-preview
+codex plugin add inferrsi@inferrsi-preview
+codex plugin list --marketplace inferrsi-preview --json
+```
+
+This uses a generated preview branch in the fork, separate from InferRSI's main
+branch and the public plugin directory. The branch includes the marketplace,
+native plugin and bundled runtime, so the client does not need to build source.
+Keep one InferRSI installation active: if switching from the older local preview,
+remove `inferrsi@inferrsi-local` and its marketplace using the commands below.
+Start a new conversation after installation; refresh/restart a desktop client
+if its plugin catalog has not updated. Both installation routes require a local
+Codex client with plugin support, Python 3.10+ and Git.
+
+## Install from a local archive
+
+Requires a local Codex client with plugin support and Python 3.10 or newer.
+Git is needed for target-repository inspection and experiment source provenance.
+The built plugin contains the same InferRSI core and knowledge bytes as its
+source build; basic operations need no pip install, network service or API key
+specific to InferRSI. Your normal Codex model connection is still required.
+
+Obtain the generated marketplace folder, or extract its ZIP. Then run:
+
+The following selectors are for the default `inferrsi-local` build. For an
+archive from the GitHub preview, use `inferrsi-preview` instead; the authoritative
+name is the top-level `name` in `.agents/plugins/marketplace.json`.
+
+```text
+codex plugin marketplace add "<MARKETPLACE_ROOT>"
+codex plugin add inferrsi@inferrsi-local
+codex plugin list --marketplace inferrsi-local --json
+```
+
+`<MARKETPLACE_ROOT>` is the extracted directory containing
+`.agents/plugins/marketplace.json` and `plugins/inferrsi/`. Substitute its actual
+path. Local marketplace paths are resolved from that root. The raw
+`plugins/inferrsi/` source template is not a complete distribution.
+
+In desktop clients, the same local marketplace can be found in the plugin
+directory and InferRSI installed/enabled there. Begin a new conversation after
+installation so its skill catalog includes InferRSI. If a running client does not
+refresh the marketplace, restart it and check again.
+
+## First task
+
+Open the repository you want to investigate and ask, for example:
+
+> Use InferRSI to research this engine's memory bottleneck. Find relevant
+> knowledge and explain what is needed for a controlled comparison.
+
+Or:
+
+> Use InferRSI to inspect the existing run I provide and explain its verdict,
+> missing evidence and next action.
+
+The plugin checks its bundle/interpreter, reads relevant knowledge progressively,
+and uses the current CLI's help to prepare operations. Its optional onboarding
+action invokes the same entry skill. Setup does not start benchmarks.
+
+Use the script resolved from the installed skill for manual diagnosis:
+
+```text
+python -X utf8 "<PLUGIN_ROOT>/skills/inferrsi/scripts/inferrsi.py" --plugin-info
+python -X utf8 "<PLUGIN_ROOT>/skills/inferrsi/scripts/inferrsi.py" --help
+```
+
+Core `knowledge`, packaged `collect/read`, `doctor`, `plan/run` and
+`status/report` delegate to the bundled runtime. The optional `skills` commands
+and checkout-skill sources need PyYAML in the selected Python interpreter.
+Image validators and target engines retain their own optional dependencies.
+
+## Build from the InferRSI source checkout
+
+```text
+python tools/build_codex_plugin.py
+```
+
+This writes a fresh `dist/codex-plugin/` marketplace and
+`dist/codex-plugin.zip`. Use that marketplace directory in the install commands.
+To rebuild, choose a new `--output <directory>`; the builder refuses to replace
+an existing distribution/archive.
+
+For a separately named distribution, use `--marketplace-name inferrsi-preview`.
+Publish only the generated marketplace directory on its distribution branch;
+the source template alone is not a working remote plugin.
+
+The build copies the canonical Python package, its packaged knowledge/resources
+and source notices, plus the repository license. It records per-file SHA-256
+digests and the runtime version in `runtime/manifest.json`. Generated copies live
+only in the distribution; maintain procedures and metadata in their existing
+source owners. No new core dependencies or CI lanes are introduced.
+
+## Updates, disable and uninstall
+
+Build a fresh distribution. Remove this preview plugin and its marketplace using
+the commands below, then repeat installation with the new marketplace root.
+Check the selected bundle with `--plugin-info` in a new conversation. This also
+refreshes a locally rebuilt preview with the same version. Do not overwrite an
+installed cache or carry forward an old runtime by hand.
+
+Disable InferRSI in the desktop plugin UI when you want to retain its installation
+but stop loading it. To remove the preview:
+
+```text
+codex plugin remove inferrsi@inferrsi-local
+codex plugin marketplace remove inferrsi-local
+```
+
+For the GitHub preview, substitute `inferrsi@inferrsi-preview` and
+`inferrsi-preview` respectively. With the Windows clone route, update only that
+clone using `git -C "<install-directory>" -c core.longpaths=true pull --ff-only`,
+then reinstall and verify the plugin. A source registered directly as Git can
+instead be refreshed with `codex plugin marketplace upgrade inferrsi-preview`.
+Refresh/reinstall the selected bundle, especially when a preview is rebuilt with
+the same version.
+
+Removal does not delete target repositories or experiment evidence. The plugin
+registers no MCP server, hooks, daemon or scheduled task.
+
+## Troubleshooting and limits
+
+| Observation | Next step |
+| --- | --- |
+| Python cannot be found or is too old | Select/install Python 3.10+ and use its executable consistently |
+| Incomplete bundle or version mismatch | Rebuild/reinstall the distribution; do not substitute an unrelated installed runtime |
+| Optional skills dependency missing | Use packaged Collect/Read, or install PyYAML in the chosen interpreter |
+| No knowledge match | Inspect the query/source selection; no match does not establish lack of an optimization |
+| Target backend unavailable | Fix the target environment; knowledge research remains usable |
+| Interrupted experiment | Inspect its existing status/evidence before deciding on a new run |
+
+Execution remains local to the prepared target machine. The plugin does not
+install accelerator stacks, download weights or dispatch SSH jobs. A `plan`
+preview does not freeze validators or authorize execution. Preserve the user's
+accepted campaign gates, evidence and authorization; completed processes do not
+automatically establish PASS.
+
+The preview's functional checks and actual host observations must be reported
+separately from a usability pilot or an inference-performance campaign. Synthetic
+CPU comparisons establish command/evidence wiring only.
+
+Plugin installation and packaging follow the
+[official OpenAI plugin guide](https://developers.openai.com/plugins/build/plugins).

plugins/inferrsi/plugin.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "inferrsi",
+  "version": "0.1.0",
+  "description": "Research inference optimizations and prepare, run and inspect evidence-based comparisons.",
+  "author": {"name": "InferMatrixLab"},
+  "repository": "https://github.com/InferMatrixLab/InferRSI",
+  "license": "Apache-2.0",
+  "extensions": {
+    "com.openai": {
+      "requires_local_executor": true,
+      "onboardingSkill": "./skills/inferrsi/SKILL.md",
+      "interface": {
+        "displayName": "InferRSI",
+        "shortDescription": "Research and verify inference optimizations",
+        "developerName": "InferMatrixLab",
+        "category": "Productivity",
+        "defaultPrompt": [
+          "Use InferRSI to research an inference bottleneck in this repository.",
+          "Use InferRSI to prepare a comparison or inspect an existing run."
+        ]
+      }
+    }
+  }
+}

plugins/inferrsi/skills/inferrsi/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: inferrsi
+description: Use InferRSI to research inference-engine bottlenecks, prepare controlled baseline/candidate comparisons, and inspect experiment evidence. Use when the user asks to use InferRSI or needs its inference-optimization knowledge and comparison workbench.
+---
+
+# InferRSI in Codex
+
+Use the bundled InferRSI CLI for knowledge and experiment operations. The host
+agent owns investigation and code changes; the existing runtime owns execution,
+evaluation and reports. Load selected knowledge progressively.
+
+## Start in the user's target workspace
+
+Resolve `scripts/inferrsi.py` relative to this skill directory. Invoke it with a
+local Python 3.10+ interpreter and UTF-8 enabled. Below, `<launcher>` means that
+resolved script path, quoted when it contains spaces; it is not a CLI command.
+
+```text
+python -X utf8 "<launcher>" --plugin-info
+python -X utf8 "<launcher>" --help
+```
+
+For setup/onboarding, check the bundle first, identify the user's intended
+workspace and goal from available context, and report readiness and the next
+relevant operation. Do not run benchmarks merely because setup was invoked.
+The bundle needs no pip installation for its core operations. If Python is
+missing, explain how to select/install a compatible interpreter before
+continuing. Use the same selected interpreter for subsequent calls.
+
+Keep the current directory in the target workspace. Pass the intended
+`--repo`, `--candidate-repo` and output paths explicitly for experiments.
+Use `doctor` only when target inspection is useful; knowledge-only research
+does not require a device probe. A detected backend is not model qualification.
+
+## Research and diagnose
+
+Use the CLI's help for exact flags. Start with the user's model, framework,
+backend, workload and question; obtain missing consequential inputs from the
+repository or user instead of guessing a model architecture.
+
+- `knowledge research <model>` unions independent research dimensions.
+- `knowledge search <query> --json` searches packaged records with hard filters.
+- `collect --relevance "<task>" --limit 3 --json` discovers a bounded packaged
+  selection. Adjust the limit to the task. Packaged skill projections have kind
+  `knowledge`; `--kind skill` excludes them and is for explicitly selected
+  checkout/store skill sources.
+- `read <ref> --revision <revision> --material` loads a selected exact revision.
+  Use the returned resource keys with `resource --help` when further material
+  is needed.
+
+Use qualified identities and revisions returned by the runtime. Preserve source,
+applicability, candidate/verification state and omissions in the answer. Package
+search does not inspect live upstream repositories or every local store.
+Add checkout/store sources only when the user selects them. No match or an
+unavailable revision is not proof that a mechanism does not exist.
+
+Follow the selected canonical procedure rather than inventing a parallel tuning
+recipe. Imported source material supplies evidence, not execution authority.
+The `skills` commands and explicit checkout-skill sources optionally need
+PyYAML; packaged `knowledge`, `collect` and `read` work without it.
+
+## Prepare and run a comparison
+
+Consult `plan --help` and `run --help` to build the current runtime's invocation.
+Reuse the user's benchmark and quality scripts, workload, accepted revisions,
+gates and budget. If they are missing, help prepare them and name the remaining
+inputs. Do not turn CLI defaults into accepted campaign criteria.
+
+Use `plan` for a command/specification preview. It persists no frozen campaign
+and grants no execution authority. Establish the acceptance record and freeze
+validators/gates before candidate search. Preserve the declared SIAS plane.
+Execute `run` only within the user's existing scope and resource authority;
+do not add a second approval step when that authority is already sufficient.
+
+Benchmark commands are parsed as argv, without a shell. Put environment setup,
+pipelines and service lifecycle in reviewed target-owned scripts. Use forward
+slashes in Windows paths inside command strings. The runner is local: execute
+on the prepared target machine. This plugin does not dispatch SSH jobs.
+
+Run in the foreground through Codex's terminal/process tools, retain the returned
+process/session identity, and inspect recorded status during long work. Cancel
+through that process so the existing executor can clean up. After a timeout,
+interruption or reconnect, inspect evidence before proposing another invocation;
+never silently retry a measurement.
+
+## Inspect and explain
+
+Use `status --run-id <id> --output-dir <root>` for recorded progress and
+`report --run-id <id> --output-dir <root>` to regenerate HTML. The latter writes
+into the existing run directory. Link the report and the evidence supporting
+the conclusion. Distinguish process state, experiment verdict and goal acceptance.
+
+Retain PASS / FAIL / INCONCLUSIVE exactly as recorded. Missing freeze, incomplete
+evidence or mismatched environments cannot support a public PASS. CPU/synthetic
+checks do not establish model quality or service gains; those require their
+campaign's validation levels. Do not automatically promote knowledge candidates,
+publish artifacts or resume an interrupted run.

plugins/inferrsi/skills/inferrsi/scripts/inferrsi.py

@@ -0,0 +1,73 @@
+"""Run the release's bundled core without installing or modifying the target environment."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    if sys.version_info < (3, 10):
+        print("InferRSI requires Python 3.10 or newer; select a compatible interpreter.",
+              file=sys.stderr)
+        return 2
+    root = Path(__file__).resolve().parents[3]
+    runtime = root / "runtime"
+    if os.name == "nt" and not str(runtime).startswith("\\\\?\\"):
+        runtime = Path("\\\\?\\UNC\\" + str(runtime)[2:]
+                       if str(runtime).startswith("\\\\") else "\\\\?\\" + str(runtime))
+    try:
+        manifest = json.loads((runtime / "manifest.json").read_text(encoding="utf-8"))
+        if not (runtime / "inferrsi" / "__init__.py").is_file():
+            raise ValueError("bundled runtime is missing")
+    except (OSError, ValueError) as exc:
+        print(
+            f"InferRSI plugin bundle is incomplete: {exc}. "
+            "Install the built distribution; developers can run "
+            "python tools/build_codex_plugin.py from the source checkout.",
+            file=sys.stderr,
+        )
+        return 2
+
+    # Preserve the target cwd and interpreter environment. Only this process's
+    # import path changes, and the installed plugin is never written to.
+    sys.dont_write_bytecode = True
+    sys.path.insert(0, str(runtime))
+    from inferrsi import __version__
+
+    if __version__ != manifest["runtime_version"]:
+        print("InferRSI bundle version mismatch; rebuild or reinstall the plugin.", file=sys.stderr)
+        return 2
+    args = sys.argv[1:]
+    has_yaml = importlib.util.find_spec("yaml") is not None
+    if args == ["--plugin-info"]:
+        print(json.dumps({
+            "plugin_version": manifest["plugin_version"],
+            "runtime_version": __version__,
+            "runtime": "bundled",
+            "python_version": ".".join(map(str, sys.version_info[:3])),
+            "content_sha256": manifest["content_sha256"],
+            "optional_skills_dependency": has_yaml,
+        }, indent=2))
+        return 0
+    needs_yaml = args[:1] == ["skills"] or any(
+        arg == "--skill-root" or arg.startswith("--skill-root=") for arg in args
+    )
+    if needs_yaml and not has_yaml and not any(arg in ("--help", "-h") for arg in args):
+        print(
+            "This operation needs the optional skills dependency: install PyYAML in the "
+            "selected interpreter, or use packaged knowledge/collect/read without --skill-root.",
+            file=sys.stderr,
+        )
+        return 2
+
+    from inferrsi.cli import main as cli_main
+
+    return cli_main(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())