Extensions

What Extensions Are

Greentic has two complementary extension surfaces:

• Pack-embedded extension metadata (.gtpack) — explicit pack.yaml keys (capability offers, deployer contracts, static routes) that the runtime reads when it loads a bundle. This is the focus of most of this page.
• Standalone design-time extension packs (.gtxpack) — signed, independently published packs in four kinds (design, bundle, deploy, provider) installed into GREENTIC_EXTENSIONS_DIR and consumed by the Greentic Designer and the runtime. Design extensions are how agentic workers get their tools and guardrails. See Design Extensions below.

A pack-embedded extension adds platform behavior through explicit metadata in pack.yaml. The .gtpack authoring path is:

1. gtc wizard scaffolds the pack and captures extension answers.
2. gtc dev pack validates and builds the pack.
3. gtc setup resolves setup questions and configuration.
4. gtc start loads the packed manifest and exposes the runtime behavior.

Extensions let Greentic grow a digital-worker platform without baking every vendor, runtime service, or deployment target into application packs.

ヒント

Use gtc wizard --schema before automating extension authoring. Coding agents can read the schema, generate an answers file, and replay it with gtc wizard --answers extension-pack-answers.json.

Current Extension Keys

Greentic currently documents these active manifest extension keys:

Extension key	What it is for
greentic.ext.capabilities.v1	Component-backed capability offers: messaging, events, OAuth, MCP, state, telemetry, secrets, admin, control, observer, contracts, ops hooks, and other runtime services.
greentic.deployer.v1	Deployer contracts that describe how a deployer plans and performs deployment operations.
greentic.static-routes.v1	Public HTTP routes for static assets packaged inside a pack.

These entries are packed into the .gtpack manifest with the components, flows, assets, i18n files, and setup questions they depend on.

Capability Offers

Most extension packs use greentic.ext.capabilities.v1. A capability offer says that a component operation can provide a named capability.

pack.yaml

extensions:
  greentic.ext.capabilities.v1:
    kind: greentic.ext.capabilities.v1
    version: 1.0.0
    inline:
      schema_version: 1
      offers:
        - offer_id: messaging.webchat.inbound.01
          cap_id: greentic.cap.messaging.webchat.v1
          version: v1
          provider:
            component_ref: webchat-extension
            op: messaging.dispatch
          priority: 100
          requires_setup: true
          setup:
            qa_ref: qa/webchat-setup.json
          applies_to:
            op_names:
              - send
              - receive

The pack tooling validates the important references:

• schema_version must be 1.
• offer_id, cap_id, version, provider.component_ref, and provider.op must be present.
• provider.component_ref must point at a component in the pack or at a lock-backed component reference.
• requires_setup: true requires setup metadata and a valid setup.qa_ref.
• priority lets multiple offers for the same capability resolve deterministically.
• applies_to can narrow a capability to specific operations.

Extension Types in the Wizard

The pack wizard uses a catalog to map human-facing extension types onto the manifest keys above. These are the types currently represented by the catalog:

Wizard type	Manifest key	Purpose
messaging	greentic.ext.capabilities.v1	Chat and message transport such as WebChat, Slack, Teams, Telegram, WhatsApp, Webex, and email.
events	greentic.ext.capabilities.v1	Event sources and sinks such as HTTP webhooks, timers, queues, pub/sub, SendGrid, Twilio, audit events, and domain events.
oauth	greentic.ext.capabilities.v1	OAuth brokers, token validation, consent, and card-login surfaces.
mcp	greentic.ext.capabilities.v1	MCP tool discovery and execution integrations.
state	greentic.ext.capabilities.v1	Session, memory, checkpoint, and key-value state backends.
telemetry	greentic.ext.capabilities.v1	Logs, metrics, traces, span enrichment, and exporters.
secrets	greentic.ext.capabilities.v1	Environment, vault, Kubernetes, cloud, or custom secret brokers.
admin	greentic.ext.capabilities.v1	Setup and runtime administration surfaces.
control	greentic.ext.capabilities.v1	Lifecycle control, routing, throttling, pause/resume, and governance hooks.
observer	greentic.ext.capabilities.v1	Audit, monitoring, supervision, and observation hooks.
deployer	greentic.deployer.v1	Deployment target contracts and deployment operation flows.
runtime-capability	greentic.ext.capabilities.v1	New host/runtime services that other packs can consume.
contract	greentic.ext.capabilities.v1	Schemas, policies, rules, and validation contracts.
ops	greentic.ext.capabilities.v1	Operational hooks and automation scaffolds.
capability-offer	greentic.ext.capabilities.v1	A focused pack that mainly offers one or more capabilities.
custom-scaffold	greentic.ext.capabilities.v1	A blank extension scaffold when the named categories do not fit.

The wizard persists catalog answers in JSON under extensions/ and merges the canonical payload into pack.yaml.

Deployer Extensions

Deployer metadata uses greentic.deployer.v1, not the capability-offer schema. The validated contract has a planner flow and a set of supported deployment capabilities.

pack.yaml

extensions:
  greentic.deployer.v1:
    kind: greentic.deployer.v1
    version: 1.0.0
    inline:
      schema_version: 1
      planner:
        flow_id: flows/plan.ygtc
      capabilities:
        - capability: plan
          flow_id: flows/plan.ygtc
        - capability: apply
          flow_id: flows/apply.ygtc
        - capability: status
          flow_id: flows/status.ygtc

Validation requires schema_version: 1, a non-empty planner flow_id, no duplicate capability entries, and at least the plan capability. Supported deployer capabilities are generate, plan, apply, destroy, status, and rollback.

Static Routes

Static web assets are exposed with greentic.static-routes.v1. The assets remain ordinary files under assets/; the extension metadata declares which subdirectory should be mounted under a public HTTP route when gtc start runs the bundle.

pack.yaml

extensions:
  greentic.static-routes.v1:
    kind: greentic.static-routes.v1
    version: 1.0.0
    inline:
      version: 1
      routes:
        - id: webchat-ui
          public_path: /v1/web/webchat/{tenant}
          source_root: assets/webchat
          scope:
            tenant: true
            team: false
          index_file: index.html
          spa_fallback: index.html
          cache:
            strategy: public-max-age
            max_age_seconds: 3600

Static route paths are deliberately constrained. Public paths must live under /v1/web/, source_root must point under assets/, and team-scoped routes must also be tenant-scoped.

Design Extensions (.gtxpack)

Alongside the pack-embedded .gtpack metadata above, Greentic ships a design-time extension system: standalone, signed .gtxpack packs that are published independently and installed into GREENTIC_EXTENSIONS_DIR. There are four kinds:

Kind	What it adds
design	Agentic-worker tools, guardrails, and Designer compose-time helpers (e.g. DW composers). Discovered from GREENTIC_EXTENSIONS_DIR/design/.
bundle	Bundle-level helpers applied when a bundle is assembled.
deploy	Deployment targets and operations beyond the built-in deployers.
provider	Channel/service providers surfaced to the Designer and runtime.

Design extensions are the mechanism behind agentic-worker tools and guardrails. An agentic worker’s AgentConfig references tools by extension_id + tool_name, and guardrails by capability id — both resolved against installed design extensions. Guardrails implement the greentic:extension-design/guardrail@0.3.0 WIT interface.

Design extensions are published as signed .gtxpack artifacts with the gtdx CLI to store.greentic.cloud. For authoring see:

• Agentic Workers — build a worker and its tool extension.
• Guardrail Extensions — author content-safety guardrails.
• Publishing Extension Packs — sign and publish .gtxpack artifacts.

Why Extensions Matter

Composable

Application packs can require messaging, state, secrets, OAuth, telemetry, or control without hard-coding a specific vendor.

Tenant-aware

Setup data and capability resolution can vary per tenant, team, and environment.

Observable

Observer and telemetry extensions make digital-worker activity traceable, auditable, and controllable in production.

Deployable anywhere

Deployer extensions let the same bundle target local development, Kubernetes, the three major clouds, or a custom enterprise deployer.

Two Surfaces, Not One

.gtpack and .gtxpack extensions are distinct, complementary surfaces — not old vs new:

• Pack-embedded .gtpack metadata — greentic.ext.capabilities.v1, greentic.deployer.v1, and greentic.static-routes.v1 keys authored with gtc wizard / gtc dev pack and loaded by gtc start. Covered by the sections above.
• Standalone .gtxpack design extensions — the design / bundle / deploy / provider kinds installed into GREENTIC_EXTENSIONS_DIR and published with the gtdx CLI. These power agentic-worker tools, guardrails, and Designer compose-time helpers. Covered by Design Extensions.

When deciding which to author: a pack that offers a runtime capability, deployer contract, or static route uses .gtpack metadata; an agentic-worker tool, guardrail, or Designer composer ships as a .gtxpack design extension.