azure-cost-management

AtlasClaw Providers

Reusable provider packages and starter patterns for integrating external enterprise systems with AtlasClaw.

This repository is the home for concrete provider packages such as SmartCMP and Jira. AtlasClaw core documents the loading contract; this repository documents provider behavior, auth models, field semantics, workflow patterns, and reference implementations.

What Is a Provider?

A provider is a self-contained integration package for one external system. It owns:

• connection and authentication conventions
• one or more skills for different business capabilities
• skill definitions exposed to the agent
• executable scripts or handlers that call the target system
• provider-specific documentation and reference material

What Is in This Repository?

This repository contains reusable provider packages and reference implementations:

If you are new to the model, start with:

1. providers/SmartCMP-Provider/README.md
2. providers/SmartCMP-Provider/PROVIDER.md
3. providers/jira/skills/jira-issue/SKILL.md

Provider Package Structure

AtlasClaw providers follow a simple package layout:

providers/<provider-name>/
├── PROVIDER.md              # LLM-facing provider contract
├── provider.schema.json     # Runtime/API/UI manifest
├── README.md                # Human-facing package docs
├── assets/                  # Optional icons/images
├── assistant_context/       # Optional context-aware embed routes and resolver
│   ├── routes.json          # Enterprise System path → page object → existing Skill
│   └── resolve.py           # Provider-owned object and action resolver
└── skills/
    ├── <skill-a>/
    │   ├── SKILL.md         # Skill metadata, trigger rules, entrypoints
    │   ├── scripts/         # Python handlers or helper scripts
    │   └── references/      # Provider-specific API mapping, workflows, examples
    └── <skill-b>/
        └── ...

File Responsibilities

• provider.schema.json: machine-readable manifest for runtime/API/UI and code-analysis agents. It owns catalog display metadata, config fields, auth modes, defaults, aliases, sensitive flags, and optional icon paths.
• PROVIDER.md: natural-language provider contract for LLM context and provider usage rules. Runtime must never parse schema from PROVIDER.md body tables.
• README.md: explains the provider package to human readers
• SKILL.md: declares the skill name, description, provider binding, and executable entrypoints
• scripts/: implements the actual integration logic
• references/: keeps API mappings, examples, and workflow notes close to the skill

Note: the directory name is a packaging concern, while the runtime identifier comes from provider_type in skill metadata and the corresponding key in service_providers. In this repository, SmartCMP-Provider/ maps to the runtime provider type smartcmp.

Embedded Menu and Floating UI

AtlasClaw Embedded mode provides two independent surfaces that can be deployed together or separately:

• the menu UI opens a full AtlasClaw conversation without page Context;
• the floating UI stays compact and follows supported Enterprise System pages.

Both surfaces receive the same Enterprise System Cookie authentication context. AtlasClaw host_cookie authentication resolves the same signed-in user, while the configured HostApp Provider's Cookie auth mode forwards the current request Cookie to the existing system APIs. The surfaces can also share a bootstrap-validated active Chat Session, but one does not open, replace, or control the other.

For the menu surface, the Enterprise System only needs a menu entry that embeds /atlasclaw/?embedded=1&surface=menu. It does not provide page Context. For the floating surface, the Enterprise System additionally owns the launcher and compact iframe lifecycle, supplies the exact Host Origin and a fresh nonce, and reports normalized route paths with monotonically increasing generations. Enterprise System code does not resolve business objects, choose a Provider or Skill, call Agent/Tool APIs, or duplicate confirmation UI.

Core owns surface bootstrap, the secure embedding protocol, deterministic matching, Context lifecycle, and permission revalidation. The HostApp Provider owns the floating page semantics. For the floating surface, the optional assistant_context/routes.json manifest maps normalized Enterprise System paths to:

• a stable page type;
• a provider-owned object type;
• the existing Provider Skill that owns the page workflow.

Each route uses static path segments and single-segment placeholders such as /main/items/{item_id}. AtlasClaw evaluates the manifest again whenever the Enterprise System reports a newer page generation. This makes Context matching dynamic at runtime while keeping it deterministic and auditable; an LLM does not guess which page or Skill is active.

The single Provider-level resolver loads the current business object with the request-scoped user credential and returns a bounded display projection plus the object's current object_actions. Actions can vary with object state, permissions, and available workflows. They enter the normal Chat path and the matched Skill's normal Tool, schema, confirmation, Provider, and RBAC checks; the browser does not select or invoke a Tool directly.

Use these extension rules:

• A new path for an already supported object and owning Skill normally adds one route entry.
• A new object API extends the Provider resolver's read adapter and the owning Domain Skill's action builder.
• Do not add provider-specific page mappings, action labels, or object fields to AtlasClaw Core or the generic floating UI.
• Do not put cookies, tokens, credentials, query strings, fragments, or business DTOs in route manifests or embedding messages.

See the Core Embedded integration guide for surface bootstrap, Cookie, Context, and page-message contracts.

Authentication Model

Authentication is a provider responsibility. AtlasClaw Core can pass user identity and runtime context, but each provider must obtain or derive credentials that the target system actually accepts.

That matters because one provider usually exposes multiple skills, and all of those skills must execute under the same user identity model for the target system.

Mode 1: Embedded UI

Embedded mode uses a two-layer Cookie contract:

• AtlasClaw auth.provider: "host_cookie" reads the Enterprise System Cookie and identity cookies to resolve the signed-in AtlasClaw user.
• The configured HostApp Provider uses auth_type: "cookie" to receive the request-scoped Enterprise System Cookie when it calls existing system APIs.

The Cookie remains runtime-only and is not copied into Provider Tokens, route manifests, page messages, or persisted Provider configuration. This preserves the user's existing system permissions without asking for a second sign-in.

Mode 2: Standalone AtlasClaw Deployment

In standalone deployments, AtlasClaw Core may only hold an enterprise SSO token or upstream identity assertion. That token is not automatically usable against the target platform.

In this mode, the p