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.

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 automatically receive the state.get/state.set/session.update host interface (WIT v0.6).
• 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.

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.

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.