cluxion-agentplugin-preprocessing 0.3.1

Universal agent plugin for Cluxion preprocessing, honesty contracts, clarification, Rust work queue, and resource-aware harness handoff.

cluxion-Agentplugin-preprocessing

범용 에이전트 전처리 플러그인 — Hermes, Claude Code, Codex, Grok Build에서 동일 core로 동작합니다.

Repository: https://github.com/cluxion/cluxion-Agentplugin-preprocessing

한 줄 요약

작업 시작 전에 방향·정직함·큐를 정리합니다. 연결된 AI가 cluxion_plan 등 도구를 호출하고, JSON 계약(answer_policy, host_execution)에 따라 응답합니다. 플러그인은 추가 LLM 호출 없이 결정론적 plan만 반환합니다.

범용 에이전트 + Rust-First

계층	구현
Rust (cluxion-queue)	SQLite 작업큐, atomic dispatch
Python (cluxion_runtime, adapter)	harness plan, 전처리, CLI
Agent adapter	adapters/ — Hermes plugin, Claude skill, Codex snippet

내부 hot path는 Rust. Python은 등록·JSON bridge·fallback입니다.

이 플러그인의 역할

• 정직함: context 부족 시 모른다고 답하도록 answer_policy 생성
• 명확화: 의도가 애매하면 큐 진입 전 질문 (needs_clarification)
• 작업큐: 긴 입력을 segment로 분할, checksum 보존
• 리소스 admission: RAM/CPU 압력에 따른 실행 허용 (결정론적)

모델·OAuth·provider는 host agent 소유. Cluxion은 plan·게이트·큐 메타데이터만 반환합니다.

연결된 AI가 하는 일

단계	동작
요청 수신	cluxion_plan 또는 cluxion-runtime plan
명확화 필요	clarification.questions로 사용자에게 질문
queued 모드	cluxion_queue_next → 처리 → cluxion_queue_record → cluxion_queue_brief
응답	answer_policy.required_checks 준수

설계 요약

User prompt → cluxion_plan → [clarification?] → preprocessing mode
           → answer_policy + host_execution
           → (queued) queue_next/record/brief

설계 원칙

1. 추가 AI preflight 없음 — 결정론적 plan
2. 짧은 일반 질문은 simple_answer fast path
3. 불확실 시 fake success 금지 — needs_clarification, unknown_after_check
4. opt-in — 사용자 동의 없이 권한 확대 없음

빠른 시작

pip install cluxion-agentplugin-preprocessing
cluxion-preprocess check
cluxion-preprocess enable    # Hermes

cluxion-runtime plan --surface hermes --prompt "작업 설명"

도구 (cluxion toolset, 10 tools)

Tool	설명
cluxion_plan	전처리·방향·큐·리소스 계획
cluxion_clarify	명확화 질문 목록
cluxion_bootstrap	로컬 runtime 의존성 설치/업그레이드 (예: vllm-mlx)
cluxion_serve_local	Cluxion-managed vLLM-MLX 로컬 endpoint 준비/시작
cluxion_hermes_config	로컬 OpenAI-compatible endpoint용 Hermes provider config
cluxion_queue_next / record / brief	segment 큐
cluxion_context_compress	context 사용률 초과 시 결정론적 압축 (pinned/recent 보존)
cluxion_guard	실시간 리소스 guard (status/start/stop/enforce/auto-enforce)

Hermes에서는 on_session_start hook이 guard daemon을 자동 시작합니다. CLUXION_GUARD_AUTOSTART=0 또는 false로 끌 수 있고, post_tool_call hook은 기본 30초마다 report-only auto_enforce(dry_run=True)를 실행합니다. 실제 적용은 CLUXION_GUARD_AUTO_APPLY=1 또는 true일 때만 켜집니다.

문서

• Docs/README.md — 처음 읽는 분 + 목차
• Docs/architecture.md
• Docs/design.md
• Docs/installation.md
• Docs/tools.md
• Docs/agent-surfaces.md
• Docs/rust-architecture.md

License

Apache-2.0