Skip to main content

Integrations

INTEGRATIONS

Internal Helpifyr Integrations​

jhf-shuttle-core​

  • Direction: bidirectional logical integration
  • Type: repository-intake
  • Surface: n8n_expert/, python -m n8n_expert, fabric-manifest.json
  • Auth: none
  • Stability: stable
  • Versioning: follows pyproject.toml, fabric-manifest.json, and documented contract/version files
  • Owner: jhf-shuttle repository, bundled jhf-shuttle Core-Subkomponente

Implemented:

  • jhf-shuttle bundles the reusable core package and exposes it through repo-owned CLI, API, and artifact paths.

Planned:

  • no separate first-class Fabric identity for the bundled core

External Integrations​

n8n-rest-api​

  • Direction: outgoing
  • Type: provider-contract
  • Surface: GET /api/v1/health, GET /api/v1/status, workflow and upgrade paths backed by live n8n calls
  • Auth: n8n API key
  • Stability: stable
  • Versioning: governed by upstream n8n version behavior plus local upgrade/version docs
  • Owner: upstream n8n runtime as provider, jhf-shuttle as consumer

Implemented:

  • live workflow, credential, execution, and health operations

upstream-release-sources​

  • Direction: outgoing read-only
  • Type: provider-contract
  • Surface: upstream release HTTP/tag fetches consumed by catalog and upgrade scripts
  • Auth: none for public sources
  • Stability: stable
  • Versioning: additive over upstream release metadata and local release-matrix rules
  • Owner: upstream release providers, jhf-shuttle as consumer

Implemented:

  • version-gap, release-matrix, and upgrade-intelligence inputs

optional-mission-control-api​

  • Direction: incoming
  • Type: execution-contract
  • Surface: /api/v1/health, /api/v1/status, /api/v1/openapi.json, selected read-only workflow/upgrade/catalog paths
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: partial
  • Versioning: additive over docs/MISSION_CONTROL_VERSIONING.md and openapi.json
  • Owner: jhf-shuttle

Implemented:

  • read-first status, health, workflow, catalog, upstream, and upgrade surfaces

Planned:

  • no new endpoint is required for the current Fabric baseline

jhf-dobby-optional-a2a-learning-input​

  • Direction: incoming read-only
  • Type: evidence-contract
  • Surface: GET /api/v1/evidence/a2a-handoffs/latest
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: experimental
  • Versioning: canonical contract jhf-shuttle.a2a-handoff-evidence.v1 with contract_version=1.0.0
  • Owner: jhf-shuttle publishes evidence read-only, jhf-dobby consumes optionally

Implemented:

  • canonical read-only a2a/handoff evidence payload with tenancy, correlation, and lineage fields
  • Dobby can consume this surface as optional learning input without gaining any write/control path
  • explicit degraded semantics when evidence is absent or unreadable (status=degraded + degraded_reason)
  • contract details: docs/A2A_HANDOFF_EVIDENCE_CONTRACT.md

Not allowed:

  • treating absence of Shuttle evidence as hard failure for Dobby runtime
  • using this integration as mutation/control surface for Shuttle state

helpifyr-fabric-universal-delegated-handoff-transport​

  • Direction: incoming read-only
  • Type: contract-consumer
  • Surface: GET /api/v1/evidence/delegated-handoff-transport
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: experimental
  • Versioning: projection 2026-06-02.jhf-shuttle-delegated-handoff-transport.v1
  • Owner: JaddaHelpifyr/helpifyr-fabric owns handoff admissibility and delegated closeout truth; jhf-shuttle owns transport readback only

Implemented:

  • Shuttle publishes a read-only consumer projection for Fabric-owned delegated handoff transport truth
  • callback-only paths stay explicit audit surfaces rather than fake communication success
  • accepted handoff stays distinct from delegated completion
  • contract details: docs/AGENT_DELEGATED_HANDOFF_TRANSPORT_CONTRACT.md

Not allowed:

  • local handoff admissibility shadow truth in Shuttle
  • local terminal closeout claims based only on transport acceptance

helpifyr-fabric-execution-dispatch-followthrough​

  • Direction: incoming read-only
  • Type: contract-consumer
  • Surface: GET /api/v1/evidence/execution-dispatch-followthrough
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: experimental
  • Versioning: projection 2026-07-02.jhf-shuttle-execution-dispatch-followthrough.v1
  • Owner: JaddaHelpifyr/helpifyr-fabric owns execution dispatch and execution-card semantics; jhf-shuttle owns only repo-bounded transport readback followthrough

Implemented:

  • Shuttle publishes a read-only consumer projection for the Fabric-owned Wave-5 dispatch and execution-card standard
  • ack/callback, timeout/retry, and delivery evidence stay explicit transport readbacks rather than executor or closeout truth
  • transport success and callback success stay distinct from executor completion and business closeout
  • contract details: docs/EXECUTION_DISPATCH_FOLLOWTHROUGH_CONTRACT.md

Not allowed:

  • local dispatch or execution-card shadow truth in Shuttle
  • local completion or closeout claims based only on transport or callback success

helpifyr-fabric-operator-lane-followthrough​

  • Direction: incoming read-only
  • Type: contract-consumer
  • Surface: GET /api/v1/evidence/operator-lane-followthrough
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: experimental
  • Versioning: projection 2026-07-02.jhf-shuttle-operator-lane-followthrough.v2
  • Owner: JaddaHelpifyr/helpifyr-fabric owns operator-lane, guided-next-action, recovery, and acceptance truth; jhf-shuttle owns only its repo-bounded exact-main, post-merge verify, and live-readback followthrough

Implemented:

  • Shuttle publishes a read-only consumer projection for the Fabric-owned operator-lane recovery standard
  • exact-main, post-merge verify, and live-readback requirements stay explicit and fail closed
  • local dispatch or transport evidence does not upgrade itself into lane, recovery, or closeout truth
  • contract details: docs/OPERATOR_LANE_FOLLOWTHROUGH_CONTRACT.md

Not allowed:

  • local operator-lane shadow truth in Shuttle
  • reconstructing guided-next-action from comments or implicit repo state when Fabric already publishes it
  • local green claims when exact-main, post-merge verify, or live-readback evidence is still missing

helpifyr-fabric-n8n-workflow-admission-followthrough​

  • Direction: incoming read-only
  • Type: contract-consumer
  • Surface: GET /api/v1/evidence/n8n-workflow-admission-followthrough
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: experimental
  • Versioning: projection 2026-07-02.jhf-shuttle-n8n-workflow-admission-followthrough.v1
  • Owner: JaddaHelpifyr/helpifyr-fabric owns n8n workflow admission, lifecycle, and promotion truth; jhf-shuttle owns only its repo-bounded runtime readback and execution-evidence followthrough

Implemented:

  • Shuttle publishes a read-only consumer projection for the Fabric-owned n8n workflow admission and promotion standard
  • owner runtime, execution evidence, and promotion readback requirements stay explicit and fail closed
  • callback or transport evidence does not upgrade itself into workflow admission or closeout truth
  • contract details: docs/N8N_WORKFLOW_ADMISSION_FOLLOWTHROUGH_CONTRACT.md

Not allowed:

  • local workflow admission, lifecycle, or promotion shadow truth in Shuttle
  • local workflow catalog truth that bypasses Fabric admission
  • local green claims when owner runtime readback, execution evidence, or promotion readback is still missing

helpifyr-fabric-plan-studio-review-transport​

  • Direction: incoming read-only
  • Type: contract-consumer
  • Surface: GET /api/v1/evidence/plan-studio-review-transport
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: experimental
  • Versioning: projection 2026-06-03.jhf-shuttle-plan-studio-review-transport.v1
  • Owner: JaddaHelpifyr/helpifyr-fabric owns planning, review, and materialization truth; jhf-shuttle owns transport readback only

Implemented:

  • Shuttle publishes a read-only consumer projection for Fabric-owned Plan Studio review transport truth
  • transport completion stays distinct from review acceptance
  • accepted review stays distinct from materialization readiness
  • contract details: docs/PLAN_STUDIO_REVIEW_TRANSPORT_CONTRACT.md

Not allowed:

  • local review acceptance shadow truth in Shuttle
  • local materialization-readiness claims based only on transport or review completion

helpifyr-fabric-weft-workspace-handoff-transport​

  • Direction: incoming read-only
  • Type: contract-consumer
  • Surface: GET /api/v1/evidence/weft-workspace-handoff-transport
  • Auth: optional bearer token via JHF_SHUTTLE_API_TOKEN
  • Stability: experimental
  • Versioning: projection 2026-06-20.jhf-shuttle-weft-workspace-handoff-transport.v1
  • Owner: JaddaHelpifyr/helpifyr-fabric owns Weft workspace admission, permission, promotion, and closeout truth; jhf-shuttle owns transport readback only

Implemented:

  • Shuttle publishes a read-only consumer projection for Fabric-owned Weft workspace handoff transport truth
  • Spindle and Loom handoff lanes remain explicit, correlation-bound, and idempotency-safe
  • transport completion stays distinct from Spindle materialization and Loom record completion
  • contract details: docs/WEFT_WORKSPACE_HANDOFF_TRANSPORT_CONTRACT.md

Not allowed:

  • local Weft handoff admission shadow truth in Shuttle
  • local Spindle or Loom truth claims based only on transport delivery
  • direct Weft-to-owner coupling where admitted Shuttle transport is required

helpifyr-fabric-boost-bounded-scheduling​

  • Direction: incoming read-only capacity and lifecycle truth; outgoing owner evaluation evidence
  • Type: contract-consumer / orchestration-evaluator
  • Surface: contracts/boost/bounded-scheduling-dlq.v1.json
  • Auth: no credentials in the contract or evaluator evidence
  • Stability: experimental, v1.4 Boost program
  • Owner: JaddaHelpifyr/helpifyr-fabric owns capacity and revocation semantics; jhf-shuttle owns bounded queue evaluation and transport readback; jhf-n8n-expert owns n8n operations

Implemented:

  • finite activation batch and tenant/runtime/deployment concurrency checks
  • deterministic 0-300 second jitter
  • explicit deferred outcomes for capacity, recovery, and DLQ pressure
  • bounded retry budget and DLQ ceiling
  • revocation/suspension quarantine with no runnable queued outcome
  • one recovery item per scheduling pass
  • 1000-item bounded refresh fixture and contract validator

Not allowed:

  • unbounded worker creation
  • local replacement of Fabric capacity or lifecycle truth
  • n8n workflow mutation from this evaluator
  • production Write admission or secret resolution

jhf-spool-paddle-webhook-handoff​

  • Direction: outgoing operator-verify + cross-repo handoff
  • Type: webhook-contract
  • Surface: Spool Paddle ingress path /v1/webhooks/paddle
  • Auth: provider-side Paddle signature (owned by jhf-spool + Paddle tenant admin)
  • Stability: external-blocked (provider and billing-owner owned rollout)
  • Versioning: endpoint/path is owned by jhf-spool; jhf-shuttle only consumes read-only evidence
  • Owner: jhf-spool runtime for endpoint behavior, jhf-shuttle for handoff/verification evidence

Implemented from jhf-shuttle side:

  • operator verify commands and evidence capture for live webhook path reachability
  • explicit separation between:
    • path reachability/redirect behavior (Shuttle/operator-owned evidence)
    • provider credential and signing-secret correctness (external owner responsibility)
  • documented retry/error expectation for shuttle-owned upstream senders:
    • 2xx: accepted, no retry
    • 307/308: treat as endpoint canonicalization signal, switch sender to canonical HTTPS endpoint (do not keep looping on non-canonical HTTP URL)
    • 429/5xx or network timeout: bounded exponential retry with jitter
    • 4xx (except 429): treat as terminal contract/config error and escalate

External dependency (not owned by jhf-shuttle):

  • Paddle tenant-side live webhook registration + signing-secret rotation policy
  • billing product-owner confirmation of live price-map and settlement policy

repo-version-sources​

  • Direction: outgoing read-only
  • Type: repo-read
  • Surface: pyproject.toml, fabric-manifest.json, CHANGELOG.md
  • Auth: repository read access
  • Stability: stable
  • Versioning: these files are the documented version source; no dedicated runtime /version surface exists
  • Owner: jhf-shuttle

Implemented:

  • version can be resolved from existing repository artifacts

Event Contracts​

operator-event-log​

  • Direction: bidirectional logical integration
  • Type: execution-contract
  • Surface: logs/events.jsonl
  • Auth: filesystem access
  • Stability: stable
  • Versioning: additive file contract with repo-owned event schema expectations
  • Owner: jhf-shuttle

Implemented:

  • append-only persisted operator events

optional-event-webhook-sink​

  • Direction: outgoing
  • Type: webhook
  • Surface: jhf_shuttle_EVENT_WEBHOOK
  • Auth: target-specific webhook auth
  • Stability: partial
  • Versioning: best-effort event forwarding over current event payload shape
  • Owner: jhf-shuttle as sender, target system as receiver

Implemented:

  • optional best-effort event forwarding

Planned:

  • no Fabric-specific event subscription contract is implemented yet

mailbox-jetstream-delivery​

  • Direction: bidirectional logical integration
  • Type: message-bus
  • Surface: mailbox adapter /publish, /healthz, configured NATS/JetStream stream and subjects
  • Canonical self-stack host-facing probe surface: http://<host>:58815/healthz via JHF_SHUTTLE_MAILBOX_HEALTH_HOST_PORT
  • Shuttle-owned OpenClaw evidence-forwarding surface: docs/OPENCLAW_HIGH_SEVERITY_EVIDENCE_FORWARDING_CONTRACT.md
  • Shuttle-owned host probe/publish path for optional OpenClaw evidence relay: http://<host>:58815/healthz and POST http://<host>:58815/publish
  • OpenClaw-plus compatibility endpoint contract: OPENCLAW_PLUS_SHUTTLE_URL=http://<internal-runtime-redacted>:58805/healthz; this decommissioned endpoint is not valid canonical Shuttle presence evidence.
  • Auth: optional publish token plus environment-specific NATS auth
  • Stability: partial
  • Versioning: product-local callback and delivery contract; no Fabric version contract
  • Owner: jhf-shuttle operator runtime

Implemented:

  • durable publish, session-serialized delivery, callback/result paths
  • stable owner contract for optional jhf-openclaw-env high-severity evidence forwarding on the Shuttle stack

Planned:

  • deeper semantics alignment only; no new orchestration model

MCP Integration​

mcp-status​

  • Direction: incoming
  • Type: mcp
  • Surface: bounded read-only verifier python scripts/verify_mcp_readback_lane.py; no standalone MCP runtime endpoint in this repository
  • Auth: n/a
  • Stability: partial
  • Versioning: additive over existing workflow/runtime read contracts
  • Owner: jhf-shuttle

Implemented:

  • repo-owned read-only lane for n8n workflow list/read, execution status readback, and Shuttle runtime visibility
  • verifier output declares read_only=true and mutation_allowed=false
  • fail-closed classification when live n8n, host SSH n8n readback, or the canonical Shuttle runtime is stale

Planned:

  • if Fabric ever consumes MCP-shaped metadata here, it must be layered on existing repo contracts rather than a new runtime invented for this repository

Planned Connections​

Future jhf-fabric connection​

jhf-fabric-read-contract​

  • Direction: outgoing read-only
  • Type: compatibility-shim
  • Surface: fabric-manifest.json, docs/FABRIC_TOOL_PROFILE.md, /api/v1/status, docs/CAPABILITIES.md
  • Auth: repository read access plus optional API bearer token
  • Stability: planned
  • Versioning: additive over current manifest and documented contract/version files
  • Owner: jhf-shuttle as producer, jhf-fabric as reader

Implemented:

  • Fabric can already read manifest, docs, and selected read-first API surfaces.
  • Live deployment contract route is provided by jhf-fabric API deployment contracts; exact path and unauthenticated response code are deployment-owned and must be verified in the target runtime.
  • jhf-fabric-platform-n8n (:35678) is a separate runtime and is not the deployment-endpoint-contract API surface.

Planned:

  • registration/discovery, topology hints, and policy hints remain documentation-only gaps

jhf-fabric-combination-profiles​

  • Direction: outgoing read-only
  • Type: compatibility-shim
  • Surface: /api/v1/combinations/profiles (Fabric-owned runtime surface)
  • Auth: Fabric deployment specific (this repository does not define auth semantics for that route)
  • Stability: stable (Fabric-owned truth contract)
  • Versioning: follows Fabric combination profile contract family and downstream read compatibility
  • Owner: JaddaHelpifyr/helpifyr-fabric as truth owner, jhf-shuttle as read-only consumer

Implemented:

  • jhf-shuttle consumes Fabric combination truth read-only and does not define local bundle/detection truth.
  • Supported profile keys for Shuttle preparation:
    • fabric-warp-shuttle
    • fabric-shuttle-bobbin
    • fabric-warp-shuttle-bobbin
    • shuttle-standalone-openclaw
  • Mismatch/stale posture must remain explicit when Fabric readback is unavailable or conflicting.

Not allowed:

  • deriving active bundle truth from local dashboard, workflow, or runtime heuristics
  • opening a second local truth family for bundle or detection semantics

jhf-fabric-contract-governance​

  • Direction: outgoing read-only
  • Type: compatibility-shim
  • Surface:
    • GET /api/v1/contracts/jarvis
    • GET /api/v1/contracts/jarvis/readiness
    • GET /api/v1/contracts/registry
    • GET /api/v1/contracts/families
    • GET /api/v1/contracts/schemas
    • GET /api/v1/contracts/matrix
  • Auth: Fabric deployment specific (this repository does not define auth semantics for these routes)
  • Stability: stable (Fabric-owned truth contract)
  • Versioning: accepted versions are read from Fabric matrix and mirrored as explicit consumer declaration in fabric-manifest.json
  • Owner: JaddaHelpifyr/helpifyr-fabric as truth owner, jhf-shuttle as read-only consumer

Implemented:

  • declared Fabric contract families and accepted versions in fabric-manifest.json:
    • helpifyr-schema-governance-docs-standard -> 1.0.0
    • helpifyr-schema-governance-wiki-governance -> 1.0.0
    • helpifyr-schema-governance-asyncapi-catalog -> 1.0.0
    • helpifyr-schema-governance-event-catalog -> 1.0.0
    • helpifyr-schema-governance-admission-governance -> 1.0.0
    • helpifyr-identity-surface-access-projection -> 1.0.0
    • helpifyr-identity-surface-admission-truth -> 1.0.0
    • helpifyr-identity-surface-lifecycle-truth -> 1.0.0
    • trace-envelope.v1 -> 1.0.0
    • step-envelope.v1 -> 1.0.0
    • guardrail-decision.v1 -> 1.0.0
    • skill-lifecycle.v1 -> 1.0.0
    • a2a-handoff.v1 -> 1.0.0
    • helpifyr-schema-governance-jarvis-adoption-status -> 1.0.0
    • document-ocr-event-catalog.v1 -> 1.0.0
    • helpifyr-weft-promotion-mode-v1 -> 1.0.0
  • local shadow-truth guardrails:
    • no local schema family definitions for these Fabric-owned families
    • no local accepted-version override
    • no local JARVIS lifecycle/closure shadow truth
    • readiness evidence must read back from the six canonical JARVIS/Fabric surfaces
  • verify/readiness path:
    • scripts/run_fabric_contract_governance_checks.py

Not allowed:

  • defining local canonical versions for these families independent from Fabric matrix truth
  • treating repo-local docs or local lifecycle notes as replacement for Fabric JARVIS/readiness truth

jhf-fabric-n8n-projection-admission-consumer​

  • Direction: outgoing read-only + bounded local execution
  • Type: compatibility-shim
  • Surface:
    • GET /api/v1/contracts/admission-governance
    • GET /api/v1/contracts/matrix
    • local artifact contracts/n8n_projection_contract.v1.json
  • Auth: Fabric deployment specific (this repository does not define auth semantics for these routes)
  • Stability: pilot
  • Versioning: local projection contract key jhf-shuttle.n8n-projection.v1 and Fabric admission-governance family compatibility
  • Owner: JaddaHelpifyr/helpifyr-fabric for decision truth, jhf-shuttle for bounded executor behavior

Implemented:

  • explicit consumer/executor boundary for projection execution
  • explicit projection operations, revocation handling, and orphan handling
  • local execution rejects any operation that is not explicitly allowed by Fabric decision payload

Not allowed:

  • local semantic reinterpretation of allow/deny/revoke/orphan decisions
  • local override or escalation of Fabric-declared operation allow-list

jhf-fabric-n8n-application-verdict-consumer​

  • Direction: outgoing read-only + bounded local execution
  • Type: compatibility-shim
  • Surface:
    • GET /api/v1/contracts/admission-governance
    • GET /api/v1/contracts/matrix
    • local artifact contracts/n8n_application_contract.v1.json
  • Auth: Fabric deployment specific (this repository does not define auth semantics for these routes)
  • Stability: pilot
  • Versioning: local application contract key jhf-shuttle.n8n-application.v1 and Fabric admission-governance family compatibility
  • Owner: JaddaHelpifyr/helpifyr-fabric for verdict truth, jhf-shuttle for bounded disable/delete/revoke execution

Implemented:

  • explicit disable/delete/revoke application contract for the n8n lane
  • explicit residual permissions diagnosis + surfacing in local evaluation output
  • executor blocks any operation not explicitly allowed by Fabric verdict payload

Not allowed:

  • local verdict override or semantic reinterpretation
  • local suppression of residual permission findings

Read-First Boundary​

  • Fabric may read manifest, docs, selected read-only API paths, and repo/file artifacts.
  • Current verify path is read-first only.
  • No write-back, workflow mutation, mailbox publish, or policy-file mutation is implemented for Fabric.

Not Allowed​

  • treating bundled jhf-shuttle as a second equal Fabric registration from this repository
  • inferring a dedicated /readyz, /version, /metrics, or topology endpoint that the repository does not actually expose
  • using Fabric as a control plane for workflow mutation, mailbox publish, or policy-file writes

Standalone Versus Integrated Contract View​

Contract AreaStandalone (implemented)Integrated (implemented)Integrated (planned)
execution ownershiptool-local CLI/API/compose pathsread-first metadata/status consumption onlyFabric registration/discovery contract
secret and credential sourceoperator env/env-file (N8N_API_KEY, optional API token, optional publish token); canonical source path for self-stack is contract-bound in contracts/n8n_api_key_source_contract.v1.jsonno Fabric secret injection path implementedexplicit shared credential handoff contract; consumer materialization in jhf-openclaw-env/jhf-deployment must follow source contract (refs: jhf-openclaw-env#174, jhf-deployment#249)
shared servicesoptional local NATS/mailbox pathnone attached through Fabric contracts yetbounded shared-service attachment once HF-047/050 contracts stabilize
shared Postgresnot used as shared Fabric servicenoneoptional metadata-only path if approved
migrate standalone to integratedmanual/operator-controlledno automatic adoption runtimeadopt-first protocol alignment when contract is finalized

Verification Surface Contract​

Current bounded verify surfaces used across both modes:

  • scripts/run_mission_control_checks.py
  • scripts/run_upgrade_freshness_checks.py
  • scripts/run_release_matrix_checks.py
  • scripts/run_final_release_hardening.py

No synthetic runtime endpoints are added only for contract compliance.

AGPLv3. Learn more at helpifyr.com.