Architektura: intent packs, orkiestracja i fallbacki zdolności

Status: dokument projektowy (analiza + propozycja + aktualizacja stanu 2026-07-18). Część warstw jest już zaimplementowana — patrz autonomy-implementation-status.md (CURRENT / TARGET / LEGACY). Ten plik pozostaje SSOT modelu; nie czytać §1/§2 jako „nic nie istnieje”, jeśli status mówi inaczej.

Kanoniczny: tak — ten plik jest SSOT dla modelu. Krótka nota planowa: ../plans/intent-capability-fallbacks.md.

Zakres: wzorce generyczne dla dowolnej domeny (publish, DNS, vault, HTTP check, GitHub, …). Przykład docs → Plesk httpdocs jest tylko ilustracją.

Powiązane: autonomy-recommended-solution.md (rekomendacja + ADR), adr/README.md, ../plans/autonomy-implementation-roadmap.md, autonomy-ops-status-and-open-questions.md, ../autonomy-cli-runbook.md, ../plans/docs-subactor-com-publish.md, ../../platform/docs/URI_PROCESS_AUTONOMY.md, ../../orchestrator/README.md.

1. Problem

Łatwość intencji (NL → działający plan) historycznie blokowały:

1. N-krotne ręczne podpinanie tego samego celu — frazy, katalog LLM, model AQL,

step-catalog, recipe *.urirun.json, import Planfile, ALLOW MODEL / ALLOW URI_PROCESS. CURRENT (PR2–3 partial): pack registry + derived sync redukują drift; Planfile imports nadal ręczne; dual-run do PR10.

1. Liniowy fail-fast w runTask — pierwsza porażka urirun kończy cały plan.

CURRENT (PR4 partial): on_fail / optional / retry / timeout działają; brak pełnego try_in_order; rollback = stub → rollback_failed.

1. Mylenie warstw fallbacku — transport (SFTP→FTP) należy do konektora;

alternatywy między URI do recipes/orchestratora; wybór nazwanego intentu do pack/phrase.

Bez SSOT dla named intent i policy między krokami każdy nowy cel powiela wiring. Nie jest już prawdą „brak packów / tylko fail-fast” — patrz evidence.

2. Stan obecny (zweryfikowany w kodzie)

2.1 Pipeline warstwowy (już dobry)

NL (subactor ask / subactor-run --nl)
  → intent (phrase map | OpenRouter via llm-gateway)     [nazwa modelu + situation]
  → Planfile ticket / recipe  (uri_processes)            [plan]
  → @subactor/orchestrator runTask                       [topo + AQL + OQL intent]
  → urirun-node → connector                              [HOW]

Rozdział Contract AQL (WHO) / OQL (WHAT) / URI (HOW) jest spójny z URI_PROCESS_AUTONOMY.md i README orchestratora. OpenRouter ma być **tylko intentem** — upload, vault lease, DNS, HTTP check zostają deterministyczne.

2.2 Diagram architektury (as-is)

flowchart TB
  subgraph entry [Wejście]
    NL[NL: subactor ask / subactor-run]
    Recipe[Recipe *.urirun.json]
    Ticket[Planfile ticket.inputs.uri_processes]
  end

  subgraph intent [Warstwa intent — dziś rozproszona]
    PhrasesYAML[agents/nlp-uri-phrases.yaml]
    InlinePHRASES[docs/www-sync-intent.mjs PHRASES]
    LlmCatalog[platform/config/llm-organization-intents.json]
    AqlModel[contracts/models/*.pl.aql]
    OpenRouter[OpenRouter via llm-gateway /intent/hr]
  end

  subgraph plan [Plan — dziś zduplikowany]
    StepCat[platform/config/step-catalog.json]
    UriRun[uri_processes w recipe]
    PfImport[.planfile/imports/*]
  end

  subgraph orch [Orchestrator]
    Resolve[resolvePlan]
    RunTask["runTask: topo-order, halt on first urirun fail"]
    AqlGate[checkAqlActor]
    OqlRec["OQL-shaped process.run record"]
  end

  subgraph how [Wykonanie]
    Urirun[urirun-node POST /run]
    Conn[Connectors: plesk://, github://, …]
    CapFb["Capability fallback wewnątrz URI\nnp. transport=auto SFTP→FTP"]
  end

  NL --> PhrasesYAML
  NL --> InlinePHRASES
  InlinePHRASES -->|trafienie| AqlModel
  PhrasesYAML -->|orchestrator NL| Resolve
  NL -->|brak frazy| OpenRouter
  OpenRouter --> LlmCatalog
  LlmCatalog --> AqlModel
  AqlModel --> StepCat
  StepCat --> Ticket
  Recipe --> Resolve
  Ticket --> Resolve
  Resolve --> RunTask
  RunTask --> AqlGate --> OqlRec --> Urirun --> Conn
  Conn --> CapFb

2.3 Co jest zduplikowane

Ścieżka kontrolna (core/.../routes/llm.mjs): pack-first dla docs/www, potem cold legacy adapters; pack_compare dual-run do PR10. Unika misroute do HR/onboarding.

2.4 Co już działa dobrze

Uwaga faktograficzna: nota planowa wspomina _TRANSPORT_ORDER w urirun-connector-plesk. W tym checkout umbrella nie ma zainstalowanego pakietu Python urirun_connector_plesk (connector jest zewnętrzny względem repo docs/orchestrator). Wzorzec „fallback transportu w konektorze” jest potwierdzony przez bridge (transport=auto) i dokumentację platformy; konkretna nazwa symbolu może żyć tylko na hoście urirun-node.

2.5 Gap analysis

3. Proponowany model (generyczny)

Trzy warstwy odpowiedzialności — nie mieszać:

Intent pack (SSOT: „co użytkownik miał na myśli”)
    → ekspanduje → phrases + AQL stub + llm fields + step-catalog ref + ALLOW hints
Recipe policy graph (SSOT: „jak kroki / zdolności się mają”)
    → ekspanduje → flat uri_processes (kompatybilne z Planfile) lub native interpreter
Connector capability (SSOT: „który transport/tool wewnątrz jednego URI”)
    → np. transport=auto, vault lease retry — nigdy wymyślane przez LLM

3.1 Intent packs (SSOT)

Jeden plik = jeden nazwany cel założyciela / bota (domenowo-agnostyczny).

Proponowana lokalizacja: platform/config/intent-packs/<id>.json (ew. YAML). Loader współdzielony przez:

• control (/api/llm/intent — zamiast osobnych *-sync-intent.mjs),
• agents/nlp-uri-map (generacja lub import fraz),
• opcjonalnie generator stubów AQL / wpisów llm-organization-intents.

Szkic schematu:

{
  "id": "site-httpdocs-publish",
  "version": 1,
  "aql_model": "site-httpdocs-sync.pl.aql",
  "label": { "pl": "Publikacja katalogu → httpdocs", "en": "Publish tree to httpdocs" },
  "phrases": [
    "opublikuj {{source_basename}} na {{domain}}",
    "sync {{source_basename}} to {{domain}}"
  ],
  "situation_schema": {
    "source_dir": { "type": "string", "required": true },
    "host": { "type": "string", "required": true },
    "domain": { "type": "string", "required": true },
    "remote_path": { "type": "string", "default": "/httpdocs" }
  },
  "situation_defaults": {},
  "recipe": "path/to/site-httpdocs-sync.urirun.json",
  "step_module": "create_site_httpdocs_sync_ticket",
  "allow": {
    "models": ["site-httpdocs-sync.pl.aql"],
    "uri_processes": ["plesk://*"]
  },
  "llm": {
    "may_select": true,
    "may_fill_situation": true,
    "must_not": ["invent_uri_processes", "choose_transport", "choose_vault_ids"]
  }
}

Ilustracja (docs publish — nie kanon domeny): pack docs-httpdocs-publish z situation_defaults.domain = docs.subactor.com i recipe docs. Ten sam kształt obsługuje www-httpdocs-publish, vault-entry-ensure, dns-record-ensure, https-health-check itd.

3.2 Recipe policy (zdolności, nie transporty)

Rozszerzyć UriProcess (orchestrator normalizeStep + Planfile inputs) o pola policy. Domyślne zachowanie = dzisiejszy fail-fast (on_fail: halt).

{
  "id": "capability-plan-example",
  "situation": { "domain": "example.com", "source_dir": "/path/to/tree" },
  "uri_processes": [
    {
      "id": "ensure-preflight",
      "uri": "example://host/resource/query/preflight",
      "optional": true,
      "on_fail": "continue"
    },
    {
      "id": "ensure-credential",
      "uri": "example://host/cred/command/ensure",
      "depends_on": ["ensure-preflight"],
      "on_fail": "halt",
      "human_approval": true
    },
    {
      "id": "mutate",
      "uri": "example://host/resource/command/apply",
      "payload": { "mode": "auto" },
      "depends_on": ["ensure-credential"],
      "on_fail": "halt"
    },
    {
      "id": "verify",
      "uri": "httpscheck://example.com/",
      "depends_on": ["mutate"],
      "optional": true,
      "on_fail": "ticket"
    }
  ]
}

Semantyka dla runTask:

Anti-pattern: dwa kroki sync „SFTP” i „FTP” w recipe. To jest connector capability (payload.transport: "auto"), nie recipe fallback.

Ilustracja docs: ensure-ftpuser → methods → dry-run → apply → optional https-check; transport: auto w payload sync.

3.3 Connector-level capability fallbacks

Każdy konektor deklaruje (w kodzie / metadanych URI), które warianty narzędzia próbuje wewnętrznie:

Reguła: LLM nie wybiera wariantu transportu ani vault id ad hoc. Situation slots mogą wskazać preferencję tylko jeśli schema packa na to pozwala i kontrakt to dopuszcza.

3.4 Rola LLM (OpenRouter)

Kolejność resolve intentu (propozycja):

1. Deterministic phrase map z intent packs (jak dziś docs/www przed OpenRouter).
2. LLM → pack id + situation (gdy brak frazy).
3. Recipe + orchestrator + connectors wykonują resztę.

4. Extension points w istniejącym stacku

Nie proponujemy nowego runtime ani języka. Punkty rozszerzeń:

Języki (bez zmian stacku):

• Node/TS/JS — orchestrator, control, agents phrase map, bridge OQL planner.
• Python — urirun connectors (np. Plesk), AQL/OQL runtime.
• AQL — WHO + modele intentu.
• JSON recipes + Planfile YAML — plany wykonawcze.

5. Szkice migracji

Faza 0 — dokumentacja (ten dokument)

Ustalenie warstw i non-goals. Bez zmian runnera.

Faza 1 — Intent pack SSOT (niski risk)

1. Dodać schema + 1–2 packi (np. www-httpdocs-publish, docs-httpdocs-publish).
2. Control i phrase map czytają packi; usunąć dual-maintained PHRASES arrays.
3. Test: fraza → ten sam model_name / situation co dziś.
4. Opcjonalnie: generator syncujący llm-organization-intents fields.

Faza 2 — Recipe policy w orchestratorze

1. Rozszerzyć normalizeStep + semantyka runTask (optional, on_fail) — done (PR4).
2. Test regresji: opcjonalny preflight fail → kolejne kroki nadal biegną — done.
3. Domyślnie halt — istniejące recipes bez zmian zachowania — done.
4. on_fail: ticket (hook) + timeout/retry — done; strategy: try_in_order — później.

Faza 3 — Deduplikacja planów

1. Step-catalog i Planfile import generowane z recipe (lub recipe jest jedynym SSOT,

catalog tylko wskazuje ścieżkę).

1. AQL MODUŁY wskazuje step_module z packa.

Faza 4 — Capability metadata (opcjonalnie)

Konektory eksportują deklarację „wspierane fallbacki wewnętrzne” (dla UI / audit), bez przenoszenia ich do recipes.

Kolejność ważna: najpierw pack SSOT (usuwa ból wiring), potem policy runner (usuwa ból fail-fast). Nie odwrotnie i nie „mądrzejszy LLM planner” jako pierwszy krok.

6. Non-goals

• Nowy język planowania / osobny „agent framework” poza @subactor/orchestrator.
• Przeniesienie fallbacku transportu (SFTP/FTP) do recipe jako dwóch kroków sync.
• Pozwolenie OpenRouter na emitowanie dowolnych uri_processes.
• Magazynowanie grafu policy w OQL store (OQL zostaje cienkim process.run).
• Zmiana desktop nlp2uri stubs (phrase map zostaje subactor-local).
• Implementacja w ramach tego dokumentu (tylko analiza + propozycja).
• Ops-only: DNS cutover, timeouty subprocess, certyfikaty TLS — osobne bilety.

7. Kryteria akceptacji

8. Przykłady kontekstowo niezależne

8.1 Publish drzewa plików (ilustracja: docs.subactor.com)

Pack → recipe: methods → dry-run → apply (transport: auto) → optional httpscheck. Szczegóły ops: ../plans/docs-subactor-com-publish.md.

8.2 Ensure rekordu DNS

• Intent: „ustaw CNAME X → Y”.
• Recipe: query existing → optional delete conflict (on_fail: continue) → apply → verify resolve.
• Connector: retries / provider quirks wewnątrz dns://….

8.3 Vault entry

• Intent: „ensure credential dla hosta Z”.
• Recipe: probe → ensure (human_approval jeśli create) → lease test.
• LLM wypełnia tylko host / entry_id ze schematu — nie hasło.

8.4 HTTP health po deployu

• Zawsze optional: true, on_fail: ticket — deploy może być OK przy chwilowym TLS mismatch.

9. Werdykt

Łatwość intencji w Subactor to problem SSOT + właściwej warstwy fallbacku, nie problem „lepszego OpenRouter”. Istniejący stack (phrase map, AQL, recipes, runTask, urirun, connectors) jest właściwym miejscem rozszerzeń: intent packs, recipe policy dla zdolności, capability fallbacki w konektorach, LLM wyłącznie named intent + situation slots.

10. Braki → język (inventory implementacyjny)

Werdykt: nie potrzeba nowego języka ani runtime. Braki to rozszerzenia istniejących formatów (JSON pack / recipe) i interpreterów (JS orchestrator, JS control/agents, Python konektor). Ops (DNS/TLS) = zero nowego kodu językowego.

Nie-kod (ops — bez nowego języka): DNS cutover docs.subactor.com → Plesk, cert TLS SAN, addon docroot. Live path docs: intent+recipe dry-run działają; apply pada na timeout/transport — to paramiko packaging + timeout + DNS, nie nowy planner.