Operacje, rewizje i ponawianie

Wywołanie MCP może od razu zwrócić ograniczony odczyt albo przyjąć operację, która będzie kontynuowana w Lomi. operationId potwierdza przyjęcie, a nie zakończenie komendy, zapisu, uploadu czy instalacji.

Format wyniku

Serwer zwraca standardowe pola MCP content, structuredContent i isError. Ustrukturyzowane odpowiedzi Lomi używają controlApiVersion: "1.0", status: "ok" z typowanym data albo status: "error" z code i message. Zrzuty PNG zawierają też standardowy blok obrazu MCP o typie MIME image/png.

Przykładowa odpowiedź błędu wewnątrz structuredContent:

{
  "controlApiVersion": "1.0",
  "status": "error",
  "code": "PAIRING_REQUIRED",
  "message": "Approve the pending session in Lomi Settings."
}

Operacja może zakończyć się jako failed lub outcome_unknown podczas poprawnego odczytu jej potwierdzenia. Sprawdzaj state, effectState i typowany result; samo isError: false nie potwierdza powodzenia efektu. Katalog JSON zawiera pełny schemat wyjścia każdego narzędzia.

Tożsamość i rewizje

Pole	Znaczenie
workspaceId, projectId, panelId	Jawne uprawnione cele; nie wyprowadzaj dostępu z fokusu ani nazwy.
terminalSessionId, browserGeneration, generation	Dokładny bieżący terminal/przeglądarka/Android. Panel może przetrwać konkretny proces.
leaseId	Tymczasowe upoważnienie wejścia dla własnego zasobu. Wygasa po odpowiednim przejęciu/cofnięciu dostępu.
expectedRevision	Zwykle dziesiętny domainRevision ze świeżej listy obszarów/paneli przy zmianie układu. Niektóre odczyty/eksporty używają tej nazwy dla własnego snapshotu; sprawdź schemat narzędzia.
expectedBufferRevision, documentId	Dokładny wspólny dokument edytora i rewizja tekstu.
expectedDiskRevision	SHA-256 dokładnych bajtów pliku, łącznie z kodowaniem i końcami linii.
expectedParentRevision, expectedDirectoryRevision, expectedEntryRevision	Odczyt właściwego katalogu lub wpisu, a nie licznik układu.
expectedSettingsRevision, expectedConversationRevision, expectedDraftRevision	Tokeny compare-and-set właściwej sekcji ustawień lub zapisanego Chat.
navigationId, snapshotId, elementRef, frameId	Dokument przeglądarki i cel konkretnego snapshotu; odwołania nie są trwałymi selektorami.
retryEpoch, requestKey	Trwała tożsamość żądania, gdy narzędzie jej wymaga.
inputSequence	Dziesiętny licznik uporządkowanego wejścia. Ten sam numer i payload potwierdza wcześniejsze wysłanie zamiast je powtarzać.

Nazwy pól używają camelCase. Nieznane pola są odrzucane. Wejście typu union wymaga obsługiwanego wariantu; opcjonalność pola nie usuwa warunkowych wymagań natywnych. Schemat opisuje strukturę, a natywne walidatory dodatkowo sprawdzają węższe zakresy, uprawnienia i stan. Nie dodawaj wspólnych pól do narzędzi, które ich nie przyjmują.

Wykonanie i obserwacja zmiany

Przykład tworzenia terminala:

1. Wywołaj lomi_workspace_list, a następnie lomi_connect dla zatwierdzonego obszaru. Pobierz aktualny domainRevision z listy obszarów/paneli.
2. Wywołaj lomi_terminal_create, zastępując poniższe placeholdery rzeczywistymi wartościami.
3. Odczytuj lomi_operation_get z otrzymanym operationId do zakończenia. Zachowaj sesję terminala i lease z potwierdzonego wyniku.
4. Odśwież odczyt układu przed kolejną operacją wymagającą bieżącej rewizji.

Argumenty lomi_terminal_create:

{
  "workspaceId": "WORKSPACE_ID",
  "cwdRelative": "",
  "title": "Tests",
  "expectedRevision": "CURRENT_DOMAIN_REVISION",
  "retryEpoch": "RETRY_EPOCH_FROM_CONNECT",
  "requestKey": "create-test-terminal-1"
}

Argumenty lomi_operation_get:

{
  "operationId": "OPERATION_ID_FROM_CREATE"
}

lomi_events_read udostępnia ograniczony strumień metadanych stanów operacji w zatwierdzonym obszarze. Kontynuuj z jego kursorem także po pustej stronie. Nie jest to strumień wyniku terminala, ogólna subskrypcja zdarzeń UI ani samodzielny dowód wykonania efektu.

Stany operacji

state	Interpretacja
queued	Przyjęta i trwale zapisana; czeka na wysłanie.
awaiting_user	Wymaga natywnej decyzji pokazanej w Lomi.
running	Praca została wysłana; sprawdzaj dostępny postęp/wynik.
cancelling	Poproszono o anulowanie; efekty mogą już istnieć.
succeeded	Potwierdzono warunek końcowy określony przez narzędzie.
failed	Niepowodzenie; sprawdź częściowe efekty i konkretny błąd.
cancelled	Zakończona po anulowaniu; nie oznacza cofnięcia zmian.
outcome_unknown	Lomi nie potrafi ustalić końcowego efektu. Sprawdź rzeczywisty zasób.

Osobne effectState przyjmuje none, partial, complete lub unknown. Na przykład zapis niezapisanych plików podczas zamykania obszaru może pozostawić go otwartym z częściowymi efektami. Upload może zakończyć się poprawnym załączeniem/wysłaniem zdarzeń bez potwierdzenia przyjęcia przez serwer. Uruchomienie Androida może potwierdzić dostarczenie intentu bez potwierdzenia oczekiwanego ekranu.

Tożsamość ponawiania

Natywny klucz potwierdzenia łączy sparowanie, epokę, projekt, narzędzie i klucz żądania. Fingerprint obejmuje też dokładny payload, generację celu i właściwą rewizję. Duplikat tej samej tożsamości i argumentów zwraca wcześniejszą operację. Zmienione argumenty pod tą samą tożsamością zwracają IDEMPOTENCY_CONFLICT.

Jeśli odpowiedź zaginie, zachowaj całe oryginalne żądanie, także jego rewizję. Pobierz je przez operationId lub klucz:

{
  "retryEpoch": "ORIGINAL_RETRY_EPOCH",
  "requestKey": "create-test-terminal-1",
  "tool": "lomi_terminal_create"
}

Przy wielu zatwierdzonych projektach dodaj oryginalny zakotwiczający projectId do odczytu po kluczu. Gdy wcześniejszy efekt jest znany, celowo inna operacja używa nowego klucza i świeżych odczytów. Nie generuj nowego klucza wyłącznie w celu obejścia niepewności lub odmowy.

Epoki ponawiania są ważne przez 24 godziny i przypisane do uruchomionej instancji brokera oraz połączenia. Restart nie wznawia starego upoważnienia. Potwierdzenia pozostają lokalnie, ale nie upoważniają do odtworzenia efektu ani odczytu wyników obcego połączenia.

Deduplikacja wejścia terminala używa lease i inputSequence, a nie trwałego wzorca request-key. Wejście Androida również używa uporządkowanego numeru i własnych pól ponawiania. Sprawdź każdy schemat; historie wejścia bieżącej sesji nie służą do odzyskiwania po restarcie.

Anulowanie i restart

lomi_operation_cancel anuluje oczekującą pracę albo prosi o zatrzymanie trwającej. Nie cofa zapisu, zmiany Git, uploadu, startu procesu ani wysłania do dostawcy. Ctrl+C przez lomi_terminal_interrupt potwierdza wysłanie przerwania, a nie zakończenie procesu; obserwuj oryginalną komendę.

Przed wysłaniem Lomi rezerwuje potwierdzenie w prywatnym SQLite. Brak możliwości zapisu blokuje efekt. WAL/FULL i kontrolowane przejścia zachowują niepewność po awariach. Przy ponownym otwarciu bazy niezakończone operacje przechodzą w outcome_unknown; nigdy nie są automatycznie odtwarzane.

Baza przyjmuje maksymalnie 4096 potwierdzeń i 4096 epok ponawiania. Wygasłe rekordy nie są automatycznie usuwane. RESOURCE_EXHAUSTED wymaga świadomego uzgodnienia stanu/konserwacji; ponowne połączenie nie czyści historii. Zachowaj dane i sprawdź zasoby zgodnie z poradnikiem odzyskiwania.

Kod źródłowy: wejścia i typowane wyniki, trwałe potwierdzenia, natywne upoważnienia wykonania.