greentic-runner-host

greentic-runner-host packages the Greentic runner as a standalone crate. It owns tenant bindings, the pack watcher, Wasmtime glue, canonical ingress adapters (Telegram, Teams, Slack, WebChat, Webex, WhatsApp, generic webhook, timers), the state machine (pause/resume, session/state persistence), and admin/health endpoints. Binaries such as greentic-runner or greentic-demo embed this crate instead of vendoring runtime internals.

Provider execution is provider-core only: packs declare provider runtimes via the greentic.ext.provider extension and invoke them with the provider.invoke node, instantiating greentic:provider/schema-core@1.0.0 components. Legacy typed provider worlds are not supported.

Architecture highlights

• Pack ingestion – consumes a JSON index (local path, HTTPS, or cloud bucket) via runner-core, verifies signatures/digests (PACK_PUBLIC_KEY, PACK_VERIFY_STRICT), caches artifacts under PACK_CACHE_DIR, and supports ordered overlays per tenant.
• Hot reload – PACK_REFRESH_INTERVAL drives a watcher that resolves the index, preloads packs, and swaps tenant runtimes atomically; /admin/packs/reload triggers the same path on demand. Overlays can be added/removed without touching the base pack.
• Canonical ingress – all adapters normalize raw provider payloads into the shared schema:

  {
    "tenant": "demo",
    "provider": "slack",
    "provider_ids": {
      "workspace_id": "T123",
      "channel_id": "C789",
      "thread_id": "1731315600.000100",
      "user_id": "U456",
      "message_id": "1731315600.000100",
      "event_id": "Ev01ABC"
    },
    "session": {
      "key": "demo:slack:1731315600.000100:U456",
      "scopes": ["chat","attachments","buttons"]
    },
    "timestamp": "2025-11-11T09:00:00Z",
    "text": "Hi",
    "attachments": [],
    "buttons": [],
    "entities": { "mentions": [], "urls": [] },
    "metadata": { "raw_headers": {}, "ip": null },
    "channel_data": { "type": "message" },
    "raw": { "...": "original provider payload" }
  }
  

  Canonical session keys follow {tenant}:{provider}:{conversation-or-thread-or-channel}:{user}, ensuring pause/resume and dedupe behave consistently per adapter.
• Sessions & state – the host bundles greentic-session/greentic-state. Multi-turn flows pause via session.wait; the runtime stores FlowSnapshots keyed by the canonical session, resumes on the next ingress event, and clears the entry on completion. Packs can access greentic:state/store@1.0.0 when the component declares state capability and the policy allows it.
• Telemetry & admin – optional OTLP bootstrapping (greentic-telemetry), /healthz, and bearer-protected /admin endpoints (loopback-only when ADMIN_TOKEN is unset).

Pack index format

Pack ingestion is driven by a JSON index (see examples/index.json). Each tenant entry declares a main_pack plus optional overlays, letting you layer overrides without rebuilding the base artifact:

{
  "tenants": {
    "demo": {
      "main_pack": {
        "reference": { "name": "demo-pack", "version": "1.2.3" },
        "locator": "fs:///packs/demo.gtpack",
        "digest": "sha256:abcd...",
        "signature": "ed25519:...",
        "path": "./packs/demo.gtpack"
      },
      "overlays": [
        {
          "reference": { "name": "demo-overlay", "version": "1.2.3" },
          "path": "./packs/demo_overlay.gtpack",
          "digest": "sha256:efgh..."
        }
      ]
    }
  }
}

During a reload the watcher resolves each locator (filesystem, HTTPS, OCI, S3, GCS, Azure blob), verifies digests/signatures, caches artifacts, and constructs a TenantRuntime that loads the main pack plus overlays in order. Overlay changes are safe to deploy independently—crates/tests/tests/host_integration.rs includes regression coverage.

Materialized packs

Runner can also execute a materialized pack directory (contains manifest.cbor, flows/templates, and components/<id>.wasm) or a .gtpack paired with local component files. Component resolution now prefers explicit overrides, then the materialized directory, and finally embedded archive entries; missing components raise a clear error. The desktop CLI exposes --components-dir / --components-map so distributor-produced layouts can run without the runner fetching OCI components itself.

Component cache (preview)

The runner exposes a cache module for compiled component artifacts. Each cache entry is scoped by an EngineProfile (Wasmtime version, target triple, CPU policy, and a config fingerprint) and an ArtifactKey (engine_profile_id + wasm_digest). Disk entries are namespaced under <cache_root>/v1/<engine_profile_id>/... to prevent cross-version contamination.

The cache manager is wired into component loading with disk + memory tiers. Disk entries are serialized Wasmtime components with metadata; memory entries hold Arc<Component> with bounded eviction. The API surface (CacheManager::get_component, warmup, doctor, prune_disk) is available for future CLI extensions and diagnostics.

Pause & resume semantics

Packs can pause mid-flow by emitting the session.wait component. The host persists the FlowSnapshot (current node pointer + execution state) into greentic-session. The next inbound activity for the same canonical session key (tenant:provider:channel:conversation:user) automatically resumes the stored snapshot, continues execution, and clears the entry when the flow completes. This makes multi-message LLM flows and human-in-the-loop approvals idempotent without bespoke session wiring.

OAuth broker integration

Each tenant bindings file may optionally declare an oauth block:

oauth:
  http_base_url: https://oauth.api.greentic.net/
  nats_url: nats://oauth-broker:4222
  provider: greentic.oauth.default
  env: prod        # optional, falls back to GREENTIC_ENV/local
  team: platform   # optional logical scope

When present, the host wires greentic-oauth-host, keeps a tenant-scoped client configuration, and registers the greentic:oauth-broker@1.0.0/world broker WIT world in Wasmtime. Packs that import the world can ask the host for consent URLs, exchange codes for tokens, or fetch stored tokens, while environments without the block behave exactly as before (no broker world is wired).

Quick start

use greentic_runner_host::{Activity, HostBuilder, HostConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = HostConfig::load_from_path("./bindings/customera.yaml")?;
    let host = HostBuilder::new().with_config(config).build()?;

    host.start().await?;
    host.load_pack("customera", "./packs/customera/index.ygtc".as_ref()).await?;

    let activity = Activity::text("hello")
        .with_tenant("customera")
        .from_user("u-1");

    let replies = host.handle_activity("customera", activity).await?;
    for reply in replies {
        println!("reply: {}", reply.payload());
    }

    host.stop().await?;
    Ok(())
}

Cargo features

• verify (default) – validate pack files exist before loading.
• mcp – enable tool invocation through the mcp-exec bridge.
• telemetry – wire OTLP export via greentic-telemetry.

Environment

Admin API

If ADMIN_TOKEN is set, clients must send Authorization: Bearer <token>; otherwise, admin endpoints are limited to loopback connections.

Ingress adapters

Each adapter injects the canonical payload (tenant, provider, provider_ids, session, timestamp, text, attachments, buttons, entities, metadata, channel_data, raw) and uses the same session-key policy {tenant}:{provider}:{conversation-or-thread-or-channel}:{user} enforced everywhere. Custom adapters can follow the same pattern by translating incoming payloads into an IngressEnvelope.

License

This project is licensed under the MIT License.