cluxion-agentplugin-preprocessing 0.2.0__py3-none-any.whl

cluxion_agentplugin_preprocessing-0.2.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+cluxion_agentplugin_preprocessing/__init__.py,sha256=A9ntReNZQRQa3DgiiYJ9hIRt6uExWNHp38fsKwy02Fc,137
+cluxion_agentplugin_preprocessing/cli.py,sha256=RmsJCO_10ZSfVob505cy7Jn2u472Yj9v8NtEoqktWdU,4713
+cluxion_agentplugin_preprocessing/hermes_config.py,sha256=phV08J4QR8_ys_0M5W_HlavtGCaoa-lRvYQvv1Mmd5Y,5582
+cluxion_agentplugin_preprocessing/plugin.py,sha256=AS08ETgKmQEfCb3RHD7T8glo1VP0Ujs1jI95rTDlFWE,3837
+cluxion_agentplugin_preprocessing/plugin.yaml,sha256=7HwQowiyx22q9OhRImpC2DBc7_-9qpBDbSyDI-vU10g,444
+cluxion_agentplugin_preprocessing/runner.py,sha256=J-Q8vxkG00WIMansMr76DmE3FJn55uG06Mt1e1ckv1k,8787
+cluxion_agentplugin_preprocessing/schemas.py,sha256=0hb5XlTBBnvdSdBA1X-yltQMwJs8L0hxXiDLUikdurQ,5192
+cluxion_runtime/__init__.py,sha256=9R3bErjuyM6FEpfSfwO1lltZdQUPsA7G6BQiAt6Khvk,415
+cluxion_runtime/__main__.py,sha256=VGtebB6BkEIpGdA7fgYmezhtvtdjxnns8ydEBmaVE3Y,109
+cluxion_runtime/bootstrap.py,sha256=3RpdEQjQKzgkaxnyem0WudM6kEhJFkcXtcMQBypkdk0,8913
+cluxion_runtime/cli.py,sha256=YKQzQaZ-ysQf0sZIdXSKNItaLWNslNxGgQERVmJ3a8c,11357
+cluxion_runtime/adapters/__init__.py,sha256=NncPhKu6F63Nt0FwmouKngFm8H27tdaSG5XYMTJvwJc,804
+cluxion_runtime/adapters/contract.py,sha256=YZTZW7me5EKJpPB0wfR8L32mTbct0Szh3D3vX0glwZE,3044
+cluxion_runtime/adapters/grok_build.py,sha256=ypd1YmdDb37vOyV0mITKmjVCBbICF9TvCIlaKXLfH_c,896
+cluxion_runtime/adapters/hermes.py,sha256=XSkSlNqSooOgHDi9z6bRGSazr3wNC-_tVVHt_at-T04,5499
+cluxion_runtime/adapters/spec.py,sha256=yl_ECt6DkvSXo8eQnm2kiW1ha2IP0KaC1Z6Sb47ZzgM,1144
+cluxion_runtime/core/__init__.py,sha256=UXwfInf2rE-fTsRNrFg_-mfRnOJUdyiz0KlWk-o3lXE,890
+cluxion_runtime/core/clarification.py,sha256=ctp6zpBATjn_-XC0nn7e0bd6LnZ6jTQ4VWjN_T8yQj8,6867
+cluxion_runtime/core/dispatch_store.py,sha256=XeNDLBx9iCI6JMcj_jkmesc-dNuiZKLiI-AtIYwp5K4,10150
+cluxion_runtime/core/harness.py,sha256=iGkQzawsm_AIitlUQkTnRWYx_fhxhOYm8_5RoupaJdc,11814
+cluxion_runtime/core/intent.py,sha256=0XvpWxpGqOlGl9Ij9PHCH0580T8UeHhxJgAi0zk74PQ,2411
+cluxion_runtime/core/ledger.py,sha256=Okv-6384eSs61wH9JCyLga84OkPw5wRKSWnAkGUyuNU,6547
+cluxion_runtime/core/ledger_codec.py,sha256=PRBVjdiJjyaH_diFFhDyH0yNPW563-umlibsfKdT8EI,1344
+cluxion_runtime/core/plan_codec.py,sha256=4LXMfyWGW8pFG7vJzwFpjCTwhvdQEmxRgD_fDC06t_o,5301
+cluxion_runtime/core/preprocess.py,sha256=r9Z4EB4_ujOlG0LrHqabrf5dyfyKGKDd3mqk1Gc3sQE,16040
+cluxion_runtime/core/types.py,sha256=D4AVI03wJ07ArDJyXjGX1rBrVSqD56Z7fsAFExc6gk0,5691
+cluxion_runtime/core/work_queue.py,sha256=Q5CpBhlHZTTyRtQNmnbPTgz4tL3OALhUwqoRakIgzQA,2320
+cluxion_runtime/models/__init__.py,sha256=-hKVZkjR4DWBKDX9iKtpYvgz-2RfLff_fNRP89wCnP4,477
+cluxion_runtime/models/supervisor.py,sha256=8vipSSKJL5meMQ6VBpv0V_ffCrbf9x-J7lXE89LaJ0I,5261
+cluxion_runtime/models/vllm_mlx.py,sha256=wy8oviOzxMrMZ_3pgSWnOyNhFVtiOme8ceytdk4BJ74,2623
+cluxion_runtime/resources/__init__.py,sha256=m0cIpFiMdwmho_kEgrFqIvWwGYdSb5VnVt0bXStMXOU,270
+cluxion_runtime/resources/queue_bridge.py,sha256=ykzr_uc9448iYfU7I0qQPdOGqNyLC_7NmdmN46rvmEQ,3848
+cluxion_runtime/resources/rust_bridge.py,sha256=skOQ6xNHVQjWTHonFvmciGIk9JtS8e0_MMNSWM42BZE,3401
+cluxion_agentplugin_adapters/claude/.claude-plugin/plugin.json,sha256=6HBX0BEH7KTHxOh2_f0MYo0Az-BVV42fJRDFHIZ5lv0,250
+cluxion_agentplugin_adapters/claude/skills/preprocess/SKILL.md,sha256=L-1gZLLcjnnLL9yksFL9-gVTo2qPjFjf6hVHuJxJ41k,1412
+cluxion_agentplugin_adapters/codex/config-snippet.toml,sha256=3nAYtgEQtw-e_L0OfFQSKSNz8whz3-z7W7FVpJus5FM,223
+cluxion_agentplugin_docs/cluxion-Docs/README.md,sha256=RzsFK6uf2HwMVi2_bEzjKGxw8z7NlCaqpeAIRUFMbzs,1052
+cluxion_agentplugin_docs/cluxion-Docs/architecture.md,sha256=grKiSw6IYwjIXTWnllqc9e7cd4pQJ0GnasAqOu1DQKs,1085
+cluxion_agentplugin_docs/cluxion-Docs/harness-logic.md,sha256=Lc77WmvDbvyLX93mxm_rribg_L6ZlIOK4yMdLdHeLV0,1470
+cluxion_agentplugin_docs/cluxion-Docs/honesty-preprocessing.md,sha256=h8eqRRGALSyyTS6czSssYidKstFKHPWsqb8m5-szbXI,1355
+cluxion_agentplugin_docs/cluxion-Docs/install-and-operations.md,sha256=WCGUV0dtrVJnfOl-n5GnadXjEpQZS9PmqNIv7-pudfg,940
+cluxion_agentplugin_docs/cluxion-Docs/security.md,sha256=H7c70vHw7_1CgwKf5xLSoYeqxu9PkWYy6Vu0Bw0t_QE,842
+cluxion_agentplugin_docs/github-profile/README.md,sha256=cbJ4M6JAAeKi8gdjclf3_S9-NY8mO_Qce45S_rb1NuY,1777
+cluxion_agentplugin_preprocessing-0.2.0.dist-info/METADATA,sha256=IwJfMZqJNhLPva5-I3ZlJ6wAKihOciLx475Ug1s-Dtk,4455
+cluxion_agentplugin_preprocessing-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cluxion_agentplugin_preprocessing-0.2.0.dist-info/entry_points.txt,sha256=9w1Wpx4fB1hFHD_rILgC-LK5ntKBCIqpNDKn1-0o_Aw,344
+cluxion_agentplugin_preprocessing-0.2.0.dist-info/licenses/LICENSE,sha256=ef8lElv6sdnw1KjbJWRRGIvUrR7XWqOUqmUDasF2gak,11132
+cluxion_agentplugin_preprocessing-0.2.0.dist-info/RECORD,,

cluxion_agentplugin_preprocessing-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cluxion_agentplugin_preprocessing-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,8 @@
+[console_scripts]
+cluxion-preprocess = cluxion_agentplugin_preprocessing.cli:main
+cluxion-runtime = cluxion_runtime.cli:main
+hermes-cluxion = cluxion_agentplugin_preprocessing.cli:main
+
+[hermes_agent.plugins]
+cluxion-agentplugin-preprocessing = cluxion_agentplugin_preprocessing.plugin
+hermes-cluxion = cluxion_agentplugin_preprocessing.plugin

cluxion_agentplugin_preprocessing-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,197 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work, where such license applies only to
+      those patent claims licensable by such Contributor that are necessarily
+      infringed by their Contribution(s) alone or by combination of their
+      Contribution(s) with the Work to which such Contribution(s) was
+      submitted. If You institute patent litigation against any entity
+      (including a cross-claim or counterclaim in a lawsuit) alleging that
+      the Work or a Contribution incorporated within the Work constitutes
+      direct or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate as
+      of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+      Copyright 2026 Cluxion
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          https://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

cluxion_runtime/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+"""가벼운 Cluxion Agent Harness Runtime."""
+
+from cluxion_runtime.core.harness import build_harness_plan
+from cluxion_runtime.core.types import AgentSurface, AnswerPolicy, HarnessPlan, RuntimeKind, WorkItem, WorkPriority
+
+__all__ = [
+    "AgentSurface",
+    "AnswerPolicy",
+    "HarnessPlan",
+    "RuntimeKind",
+    "WorkItem",
+    "WorkPriority",
+    "build_harness_plan",
+]

cluxion_runtime/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m cluxion_runtime` 진입점."""
+
+from cluxion_runtime.cli import main
+
+raise SystemExit(main())

cluxion_runtime/adapters/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+"""Hermes, Codex, Claude용 얇은 adapter 계약."""
+
+from cluxion_runtime.adapters.contract import render_adapter_manifest, work_item_from_adapter_payload
+from cluxion_runtime.adapters.hermes import (
+    HermesLocalEndpointPatch,
+    build_hermes_local_endpoint_patch,
+    hermes_config_patch_to_dict,
+    hermes_config_set_commands,
+    render_hermes_yaml_fragment,
+)
+from cluxion_runtime.adapters.spec import AgentAdapterSpec, default_adapter_specs
+
+__all__ = [
+    "AgentAdapterSpec",
+    "HermesLocalEndpointPatch",
+    "build_hermes_local_endpoint_patch",
+    "default_adapter_specs",
+    "hermes_config_patch_to_dict",
+    "hermes_config_set_commands",
+    "render_adapter_manifest",
+    "render_hermes_yaml_fragment",
+    "work_item_from_adapter_payload",
+]

cluxion_runtime/adapters/contract.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+"""Hermes/Codex/Claude/Grok wrapper가 공유하는 입력 계약."""
+
+import hashlib
+from typing import TYPE_CHECKING
+
+from cluxion_runtime.core.types import AgentSurface, WorkItem, WorkPriority
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+def work_item_from_adapter_payload(payload: Mapping[str, object], *, default_surface: AgentSurface) -> WorkItem:
+    """외부 wrapper JSON payload를 WorkItem으로 변환한다."""
+    prompt = str(payload.get("prompt", "")).strip()
+    if not prompt:
+        raise ValueError("prompt는 비어 있을 수 없다.")
+    work_id = str(payload.get("work_id", "")) or _stable_work_id(prompt)
+    return WorkItem(
+        work_id=work_id,
+        prompt=prompt,
+        surface=_surface(payload.get("surface"), default_surface),
+        priority=_priority(payload.get("priority")),
+        model_route=str(payload.get("model_route", "host/default")),
+        expected_ram_mb=max(0, int(payload.get("expected_ram_mb", 0))),
+        context_tokens=max(0, int(payload.get("context_tokens", 0))),
+        metadata=_metadata(payload.get("metadata"), payload.get("cwd")),
+    )
+
+
+def render_adapter_manifest(surface: AgentSurface) -> dict[str, object]:
+    """각 agent 제품에 넣을 수 있는 공통 tool manifest를 만든다."""
+    return {
+        "name": "cluxion_harness",
+        "surface": surface.value,
+        "command": ["cluxion-runtime", "plan", "--json-stdin", "--surface", surface.value],
+        "description": "Cluxion 전처리, 작업큐, Rust resource admission, 로컬 모델 route를 실행 전 계획합니다.",
+        "input_schema": {
+            "type": "object",
+            "required": ["prompt"],
+            "properties": {
+                "prompt": {"type": "string"},
+                "work_id": {"type": "string"},
+                "priority": {"type": "string", "enum": ["critical", "high", "normal", "low"]},
+                "model_route": {"type": "string"},
+                "expected_ram_mb": {"type": "integer", "minimum": 0},
+                "metadata": {"type": "object"},
+            },
+        },
+    }
+
+
+def _stable_work_id(prompt: str) -> str:
+    digest = hashlib.sha256(prompt.encode("utf-8")).hexdigest()[:16]
+    return f"work-{digest}"
+
+
+def _surface(value: object, default: AgentSurface) -> AgentSurface:
+    if value is None or value == "":
+        return default
+    return AgentSurface(str(value))
+
+
+def _priority(value: object) -> WorkPriority:
+    if value is None or value == "":
+        return WorkPriority.NORMAL
+    if isinstance(value, int):
+        return WorkPriority(value)
+    return WorkPriority[str(value).upper()]
+
+
+def _metadata(value: object, cwd: object) -> dict[str, str]:
+    metadata: dict[str, str] = {}
+    if isinstance(value, dict):
+        metadata.update({str(key): str(val) for key, val in value.items()})
+    if cwd is not None and cwd != "":
+        metadata["cwd"] = str(cwd)
+    return metadata
+
+
+__all__ = ["render_adapter_manifest", "work_item_from_adapter_payload"]

cluxion_runtime/adapters/grok_build.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+"""재구현 개발 보조용 Grok Build CLI helper.
+
+Cluxion runtime plan은 이 모듈을 호출하지 않는다.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+GROK_COMPOSER_25_FAST = "grok-composer-2.5-fast"
+GROK_BUILD_MODEL = "grok-build"
+
+
+def build_grok_composer_command(
+    prompt: str,
+    *,
+    cwd: Path,
+    model: str = GROK_COMPOSER_25_FAST,
+    json_output: bool = True,
+    check: bool = True,
+) -> tuple[str, ...]:
+    """개발자가 직접 실행할 Grok Build headless 명령을 만든다."""
+    cmd = ["grok", "-m", model, "--cwd", str(cwd)]
+    if json_output:
+        cmd.extend(["--output-format", "json"])
+    if check:
+        cmd.append("--check")
+    cmd.extend(["-p", prompt])
+    return tuple(cmd)
+
+
+__all__ = ["GROK_BUILD_MODEL", "GROK_COMPOSER_25_FAST", "build_grok_composer_command"]

cluxion_runtime/adapters/hermes.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+"""Hermes Agent 로컬 endpoint 설정 패치 생성기."""
+
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+
+@dataclass(frozen=True)
+class HermesLocalEndpointPatch:
+    """Hermes가 Cluxion 로컬 서버를 공식 custom provider로 보게 하는 패치."""
+
+    provider_key: str
+    display_name: str
+    model: str
+    base_url: str
+    context_length: int = 128_000
+    transport: str = "openai_chat"
+
+    @property
+    def provider_id(self) -> str:
+        """Hermes model.provider에 들어갈 provider ID."""
+        return f"custom:{self.provider_key}"
+
+    @property
+    def slash_model(self) -> str:
+        """Hermes 세션 안에서 바로 전환할 때 쓰는 /model 값."""
+        return f"{self.provider_id}:{self.model}"
+
+
+def build_hermes_local_endpoint_patch(
+    model: str,
+    base_url: str,
+    *,
+    provider_key: str = "cluxion-local",
+    display_name: str = "Cluxion Local",
+    context_length: int = 128_000,
+) -> HermesLocalEndpointPatch:
+    """입력값을 검증한 뒤 Hermes 설정 패치 객체를 만든다."""
+    clean_model = model.strip()
+    clean_url = base_url.strip().rstrip("/")
+    clean_key = _provider_key(provider_key)
+    if not clean_model:
+        raise ValueError("Hermes local endpoint model은 비어 있을 수 없다.")
+    if not _valid_http_url(clean_url):
+        raise ValueError("Hermes local endpoint base_url은 http(s) URL이어야 한다.")
+    if context_length <= 0:
+        raise ValueError("Hermes context_length는 양수여야 한다.")
+    return HermesLocalEndpointPatch(
+        provider_key=clean_key,
+        display_name=display_name.strip() or "Cluxion Local",
+        model=clean_model,
+        base_url=clean_url,
+        context_length=context_length,
+    )
+
+
+def hermes_config_patch_to_dict(patch: HermesLocalEndpointPatch) -> dict[str, object]:
+    """Hermes config.yaml에 병합할 수 있는 dict 패치를 만든다."""
+    provider_entry = {
+        "name": patch.display_name,
+        "base_url": patch.base_url,
+        "default_model": patch.model,
+        "transport": patch.transport,
+        "discover_models": True,
+        "models": {
+            patch.model: {
+                "context_length": patch.context_length,
+            }
+        },
+    }
+    return {
+        "providers": {
+            patch.provider_key: provider_entry,
+        },
+        "model": {
+            "provider": patch.provider_id,
+            "default": patch.model,
+            "base_url": patch.base_url,
+            "context_length": patch.context_length,
+            "api_mode": "chat_completions",
+        },
+    }
+
+
+def render_hermes_yaml_fragment(patch: HermesLocalEndpointPatch) -> str:
+    """사용자가 config.yaml에 붙여 넣을 수 있는 YAML fragment를 만든다."""
+    model = _yaml_str(patch.model)
+    base_url = _yaml_str(patch.base_url)
+    name = _yaml_str(patch.display_name)
+    provider_id = _yaml_str(patch.provider_id)
+    return "\n".join(
+        [
+            "providers:",
+            f"  {patch.provider_key}:",
+            f"    name: {name}",
+            f"    base_url: {base_url}",
+            f"    default_model: {model}",
+            f"    transport: {patch.transport}",
+            "    discover_models: true",
+            "    models:",
+            f"      {model}:",
+            f"        context_length: {patch.context_length}",
+            "model:",
+            f"  provider: {provider_id}",
+            f"  default: {model}",
+            f"  base_url: {base_url}",
+            f"  context_length: {patch.context_length}",
+            "  api_mode: chat_completions",
+        ]
+    )
+
+
+def hermes_config_set_commands(patch: HermesLocalEndpointPatch) -> tuple[str, ...]:
+    """Hermes config set으로 필수 provider 전환 상태를 만드는 명령 목록."""
+    root = f"providers.{patch.provider_key}"
+    return (
+        f"hermes config set {root}.name {_shell_quote(patch.display_name)}",
+        f"hermes config set {root}.base_url {_shell_quote(patch.base_url)}",
+        f"hermes config set {root}.default_model {_shell_quote(patch.model)}",
+        f"hermes config set {root}.transport {patch.transport}",
+        f"hermes config set {root}.discover_models true",
+        f"hermes config set model.provider {_shell_quote(patch.provider_id)}",
+        f"hermes config set model.default {_shell_quote(patch.model)}",
+        f"hermes config set model.base_url {_shell_quote(patch.base_url)}",
+        f"hermes config set model.context_length {patch.context_length}",
+        "hermes config set model.api_mode chat_completions",
+    )
+
+
+def _provider_key(value: str) -> str:
+    clean = value.strip().lower().replace("_", "-").replace(" ", "-")
+    allowed = [ch for ch in clean if ch.isalnum() or ch == "-"]
+    compact = "".join(allowed).strip("-")
+    if not compact:
+        raise ValueError("Hermes provider key는 비어 있을 수 없다.")
+    return compact
+
+
+def _valid_http_url(value: str) -> bool:
+    parsed = urlparse(value)
+    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)
+
+
+def _yaml_str(value: str) -> str:
+    escaped = value.replace("'", "''")
+    return f"'{escaped}'"
+
+
+def _shell_quote(value: str) -> str:
+    escaped = value.replace("'", "'\"'\"'")
+    return f"'{escaped}'"
+
+
+__all__ = [
+    "HermesLocalEndpointPatch",
+    "build_hermes_local_endpoint_patch",
+    "hermes_config_patch_to_dict",
+    "hermes_config_set_commands",
+    "render_hermes_yaml_fragment",
+]

cluxion_runtime/adapters/spec.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+"""외부 에이전트별 얇은 설치 계약."""
+
+from dataclasses import dataclass
+
+from cluxion_runtime.core.types import AgentSurface
+
+
+@dataclass(frozen=True)
+class AgentAdapterSpec:
+    """플랫폼별 wrapper가 알아야 하는 최소 정보."""
+
+    surface: AgentSurface
+    config_target: str
+    transport: str
+    install_hint: str
+
+
+def default_adapter_specs() -> tuple[AgentAdapterSpec, ...]:
+    """공통 런타임에 붙는 공식 adapter 목록."""
+    return (
+        AgentAdapterSpec(AgentSurface.HERMES, "~/.hermes/plugins/cluxion", "local_override", "Hermes local model helper"),
+        AgentAdapterSpec(AgentSurface.CODEX, "~/.codex/config.toml", "local_override", "Codex local endpoint helper"),
+        AgentAdapterSpec(AgentSurface.CLAUDE, ".claude-plugin/plugin.json", "local_override", "Claude Code local endpoint helper"),
+        AgentAdapterSpec(
+            AgentSurface.GROK_BUILD,
+            "project agent config",
+            "local_override",
+            "Grok Build local endpoint helper",
+        ),
+    )
+
+
+__all__ = ["AgentAdapterSpec", "default_adapter_specs"]