Tool i Plugin Factory

Cel

Tool Factory przekształca potrzebę wykonawczą w minimalny, typowany adapter. Plugin Factory pakuje jeden lub więcej narzędzi, schematów, polityk, testów, zasobów UI i dokumentacji w podpisaną jednostkę dystrybucyjną. Factory nie ma prawa samodzielnie instalować ani aktywować wytworzonego pluginu.

Karta modułu

Pole	Kontrakt
Odpowiedzialności	spec I/O/effects, generacja adaptera candidate, test harness, package manifest, provenance, review evidence.
Wejścia	use case, docelowa aplikacja/API, przykładowe dane, ograniczenia ścieżek/sieci/kont, failure semantics.
Wyjścia	tool/plugin candidate, SBOM, test report, capability proposal, risk classification.
Zależności	Tool Registry, isolated build, Artifact Store, secret scanner, policy/test engines.
Uprawnienia	create/test candidate; brak install/activate/publish i brak dostępu do realnych sekretów.
Autonomia	iteracja w izolacji; nie dodaje dowolnych zależności ani broad shell.
Walidacja	schema, effect containment, path/network tests, supply chain, fuzzing, cancellation, rollback/reconciliation.
Awaria	quarantine pakietu, revoke wersji, zachowanie poprzedniej aktywnej wersji.

Kontrakt narzędzia

Narzędzie ma jeden wyraźny czasownik i obiekt, np. office.create_document, blender.render_scene, camera.read_clip, schedule.propose_changes. Manifest definiuje:

• dokładne typy wejść i wyjść oraz limity rozmiaru;
• deklarowane skutki i wymagane capabilities;
• dozwolone roots, pliki, endpointy, accounts i destinations;
• klasę idempotency oraz klucz biznesowy;
• timeout, cancellation i checkpoint;
• wymagania CPU/GPU/RAM/aplikacji;
• redakcję logów i politykę danych;
• walidatory oraz kody błędów;
• procedurę reconciliation lub kompensacji;
• pochodzenie kodu i zależności.

Niedozwolone są manifesty typu „uruchom dowolną komendę”, „wykonaj skrypt podany przez model”, „zapisz pod dowolną ścieżką” albo „wyślij HTTP na dowolny URL”. Jeśli aplikacja oferuje skryptowanie, adapter eksponuje mały, typowany podzbiór operacji lub uruchamia zweryfikowany, wersjonowany skrypt z parametrami schema.

Pipeline budowy

flowchart LR
    U["Use case"] --> C["Contract-first spec"]
    C --> G["Candidate adapter"]
    G --> S["Static + secret + SBOM"]
    S --> X["Isolated contract tests"]
    X --> E["Effect observation"]
    E --> V["Signed package candidate"]
    V --> R["Independent review"]
    R --> I["Osobny install approval"]
    I --> A["Shadow / activation approval"]

Build nie korzysta z niekontrolowanej sieci. Zależności pochodzą z zatwierdzonego, hashowanego źródła. SBOM i pliki źródłowe są częścią dowodu. Wynik builda jest reprodukowalny albo wyraźnie opisuje elementy niedeterministyczne.

Plugin Manifest

Pakiet zawiera identity/version, publisher, licencję, podpis, minimalną wersję platformy, tool manifests, migrations, policy fragments, UI surfaces, data classes, accounts, network destinations, test fixtures, rollback/disable procedure i support window. Plugin nie może w hooku instalacyjnym aktywować narzędzia, zmieniać polityki ani pobierać dodatkowego kodu.

Rejestr i lifecycle

Tool przechodzi: candidate → validated → shadow → review_pending → active → suspended/deprecated/revoked. Zmiana kodu, schema, efektu lub zależności tworzy nową wersję. active jest wpisem Registry podpisanym przez uprawnionego operatora, nie flagą w pakiecie. Agent może prosić o narzędzie, ale nie wywoła wersji nieaktywnej.

Przykładowe polecenia

• „Przygotuj adapter do odczytu statusu renderu z DaVinci; tylko odczyt, bez sterowania kolejką.”
• „Zbuduj narzędzie do tworzenia candidate wydarzenia w kalendarzu, bez publikacji.”
• „Przetestuj plugin magazynowy na symulatorze 10 tysięcy zdarzeń i złośliwych payloadach.”
• „Pokaż diff capabilities między pluginem 2.3 i 2.4 przed aktualizacją.”

Pełny przebieg

Dla adaptera kalendarza Factory rozdziela operacje: read availability, propose event, create event i cancel event. Pierwsze dwie mogą być bezpieczniejsze; create/cancel mają osobne capability oraz account/destination scope. Testy obejmują strefy czasowe, konflikt terminów, duplikaty, expiry tokenu, brak sieci, replay i log redaction. Candidate plugin nie ma dostępu do realnego konta. Po review operator instaluje pakiet, a następnie osobno aktywuje określone narzędzia dla wybranych projektów.

Walidacja

Walidacja obejmuje strict schema, unknown fields, duże wejścia, Unicode, symlinki/reparse points, path traversal, SSRF, przekierowania, retry, przerwanie procesu, obserwowane efekty i nieujawnienie sekretu. Dla desktop automation testuje się focus, DPI, różne layouty i nieoczekiwane modalne okno. Dla fizycznego urządzenia wymagane są interlock, bezpieczny stan oraz test na symulatorze.

Błędy, ryzyka i awaria

Główne ryzyka to supply-chain compromise, dependency confusion, ukryte pobranie kodu, szerszy efekt niż deklarowany i utrata kompatybilności aplikacji. Niezgodność efektu natychmiast blokuje wersję. Gdy plugin powoduje incydent, Tool Registry oznacza go suspended/revoked, unieważnia niezrealizowane grants i zatrzymuje nowe leases. Dane i artefakty pozostają dostępne przez neutralne formaty; usunięcie pluginu nie może usuwać historii audytu.