threadlight-connect

Files (5)

• SKILL.md
• connect-manifest.schema.json · references/
• data-contract.schema.json · references/
• connect.py · scripts/
• test_connect.py · tests/

SKILL.md (first lines)

# Threadlight Connect — swap the mock, prove the real

The **CONNECT** leg: the step between "a pilot works against mocked tools"
and "a pilot is safe to point at a real endpoint." `threadlight-design` /
`threadlight-demo-data-factory` scaffold pilots against **mocked** Foundry
tools (a JSON sample file standing in for a real backend). This leg is the
one place in the pipeline that turns a mock into a real integration — and it
never does so on trust. It is a **manual handoff**: `threadlight-auto` does
not run this leg for you, because swapping to a real endpoint is an
operator decision that requires operator-supplied evidence.

> **Why "evidence-based."** An endpoint that *responds* is not the same as an
> endpoint that is *safe to depend on*. This leg only ever calls a swap
> `real-verified` after three independent, machine-checked facts hold at
> once: (1) the real response **conforms** to the contract the tool source
> code actually reads, (2) OBO (on-behalf-of) evidence shows the call was
> **user-scoped**, and (3) the **required roles** have been revalidated
> against the **current** agent identity — not a stale grant from a previous
> publish. No endpoint call is ever verified without evidence: this script
> never calls the real endpoint itself; the caller supplies the captured
> real response and evidence (e.g. from a manual test call made through
> `entra-agent-id`, the catalog skill that owns the actual OBO/OAuth token
> exchange).

## What this skill does and does not do

- **Does:** extract a data contract, generate conformance tests, check
  conformance, gate the mock → real state transition on conformance + OBO +
  role evidence, and — only with `--apply` and only once fully verified —
  transactionally update `specs/SPEC.md`, the effective MCP config
  (`infra/mcp-config.json` or the caller's actual equivalent) — pointing
  `servers/<tool>.url` at the validated `--real-endpoint` — and the
  `connect-manifest.json` together, rolling back a partially-applied write so
  the three never diverge. The real endpoint URL is persisted **only** in
  mcp-config.json; the manifest records just safe `endpoint_configured` /
  `endpoint_verified` booleans, never the URL.
- **Does NOT** map or rename customer-specific fields. Field **mapping**
  (e.g. `cust_id` → `customer_id`) is explicitly out of scope — this leg
  proves *conformance* between a mock contract and a real response; it does
  not transform payloads. Field mapping is a downstream, customer-specific
  concern left to the operator.
- **Does NOT** perform the OBO/OAuth token exchange itself. OBO handling here
  is scaffolding only: it validates the *shape* of OBO evidence the caller
  supplies and folds it into the state machine. The actual Entra Agent
  Identity / on-behalf-of implementation is owned by the upstream
  `entra-agent-id` catalog skill (see "See also" below) — this leg composes
  with it, it does not replace it.
- **Does NOT** call the real endpoint. No network call is made by
  `scripts/connect.py`. Every phase operates on evidence the caller already
  captured (tool source text, a mock sample, a captured real response, OBO
  evidence, role evidence).

## The state machine

Exactly four states — `mock`, `real-unverified`, `real-verified`,
`real-drift`:

| `target_state` | When |
|---|---|
| `real-drift` | Field-level conformance failed (missing required field, or a type mismatch) against a captured real sample that **had records to check**. |
| `real-unverified` | Conformance could not be verified — either the real response had **no items** (empty/missing `items`: insufficient evidence, never a vacuous pass), or conformance passed but OBO evidence is missing/not user-scoped, or required roles are not revalidated against the **current** agent identity. The latter includes the cases where **no `--current-agent-identity` was supplied at all** and where the revalidation names a **stale/mismatched** identity. |
| `real-verified` | Conformance passed against a **non-empty** real sample **and** OBO evidence is present and user-scoped **and** required roles are revalidated against a **supplied** current agent identity that the evidence names exactly. |

Required-role revalidation is **never opt-in**: a real apply requires
`--current-agent-identity`, and the role evidence must record exactly that
identity. Omitting the current identity, or supplying one the evidence does
not match, holds the swap at `real-unverified` and edits nothing.

`integration_state` is the **persisted** current state (read from a prior
`connect-manifest.json`; defaults to `mock`). It only ever advances on a
**successful** `--apply` — a failed or unverified transition never edits it,
and never edits `SPEC.md` / the MCP config. Publishing or **republishing**
always re-runs required-role revalidation against the current agent
identity before a swap can be called `real-verified` again — a role grant
recorded for a previous identity does not carry over.

## Phases

```
inspect          read the tool source + the mock sample
contract         extract_contract(): fields the source actually READS —
                 never sample keys that are merely present but unread
generate-tests   write an executable, dependency-free conformance test
                 module into the generated project (written every run)
verify           check_conformance(): field-level diff against a captured
                 real sample — {field, expected, actual, path} per diff;
                 an empty/missing real response is unevaluated, not a pass;
                 a non-object row is itself a difference at $.items[i]
plan             build_apply_plan(): file-by-file plan, always computed,
                 read-only, no writes — even in a dry run
apply            only with --apply AND target_state == real-verified AND a
                 validated --real-endpoint: builds and fully validates the
                 final manifest FIRST, points servers/<tool>.url at the real
                 endpoint, then transactionally updates specs/SPEC.md + the MCP
                 config + connect-manifest.json together (an in-process failure
                 after any write — or a failed post-apply endpoint re-read —
                 rolls every applied file back to its prior bytes/mode) and
                 records only the production changed paths
emit             on the non-apply / unverified path, write
                 specs/connect-manifest.json — shared envelope,
                 schema-validated, atomic, no credentials/tokens/customer
                 payloads (on a verified apply the manifest is committed
                 inside the transaction above instead)
```

## Usage

```bash
# Dry run: always safe. Computes target_state + a nonempty apply plan;
# never touches SPEC.md / mcp-config.json. --evidence-captured-at is optional:
# it records WHEN the real evidence was captured as freshness.source_oldest_at
# (omit it when unknown — it is then recorded as null, never faked).
python3 scripts/connect.py \
  --project-root ../my-pilot \
  --tool-name returns_get_case \
  --tool-source-file tool_source.py \
  --sample-file mock_sample.json \
  --real-response-file real_response.json \
  --obo-evidence-file obo_evidence.json \

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills